gsd-pi 2.76.0 → 2.77.0-dev.1594b263e

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

@@ -1,6 +1,6 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { mkdirSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { mkdirSync, rmSync, writeFileSync, readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
@@ -288,6 +288,136 @@ describe("workflow MCP tools", () => {
     }
   });
 
+  it("#4477 gsd_task_complete forwards every schema field to the executor (regression for destructure-rebuild bug class)", async () => {
+    // Locks in the class-fix from PR #4477 review: handleTaskComplete previously
+    // destructured args into a hand-listed set of fields and rebuilt the call
+    // payload, which silently dropped ADR-011's `escalation` field (and any
+    // future schema field added without updating the rebuild). The fix passes
+    // `args` through directly, matching the spread pattern of sibling
+    // handlers. This test verifies the contract by injecting a mock executor
+    // module that captures the args, calling gsd_task_complete with an
+    // `escalation` payload, and asserting the field reached the executor.
+    const base = makeTmpBase();
+    const capturePath = join(base, "captured-args.json");
+    const mockModulePath = join(base, "mock-executors.mjs");
+    const prevModule = process.env.GSD_WORKFLOW_EXECUTORS_MODULE;
+    const prevCapture = process.env.GSD_TEST_TASK_COMPLETE_CAPTURE_PATH;
+    try {
+      // Mock module: implements the WorkflowToolExecutors shape.
+      // executeTaskComplete writes its received args to disk for assertion.
+      // Other executors are no-op stubs to satisfy isWorkflowToolExecutors.
+      const mockSource = `
+import { writeFileSync } from "node:fs";
+
+const noop = async () => ({ content: [{ type: "text", text: "noop" }] });
+
+export const SUPPORTED_SUMMARY_ARTIFACT_TYPES = ["SUMMARY", "UAT", "CONTEXT", "PLAN"];
+export const executeMilestoneStatus = noop;
+export const executePlanMilestone = noop;
+export const executePlanSlice = noop;
+export const executeReplanSlice = noop;
+export const executeSliceComplete = noop;
+export const executeCompleteMilestone = noop;
+export const executeValidateMilestone = noop;
+export const executeReassessRoadmap = noop;
+export const executeSaveGateResult = noop;
+export const executeSummarySave = noop;
+
+export const executeTaskComplete = async (params, projectDir) => {
+  const capturePath = process.env.GSD_TEST_TASK_COMPLETE_CAPTURE_PATH;
+  if (capturePath) {
+    writeFileSync(capturePath, JSON.stringify({ params, projectDir }, null, 2));
+  }
+  return {
+    content: [{ type: "text", text: "mock task complete" }],
+    details: { taskId: params.taskId },
+  };
+};
+`;
+      writeFileSync(mockModulePath, mockSource, "utf-8");
+      process.env.GSD_WORKFLOW_EXECUTORS_MODULE = mockModulePath;
+      process.env.GSD_TEST_TASK_COMPLETE_CAPTURE_PATH = capturePath;
+
+      // Fresh import bypasses the cached workflowToolExecutorsPromise so the
+      // mock module is actually loaded for this test.
+      const { registerWorkflowTools: freshRegisterWorkflowTools } = await import(
+        `./workflow-tools.ts?escalation-test=${randomUUID()}`
+      );
+      const server = makeMockServer();
+      freshRegisterWorkflowTools(server as any);
+      const taskTool = server.tools.find((t) => t.name === "gsd_task_complete");
+      assert.ok(taskTool, "task tool should be registered");
+
+      // Mirrors the ADR-011 escalation schema: question + 2-4 options
+      // (each with id/label/tradeoffs) + recommendation + rationale +
+      // continueWithDefault flag.
+      const escalationPayload = {
+        question: "Should the auth flow use OAuth or PAT?",
+        options: [
+          { id: "A", label: "OAuth", tradeoffs: "Best UX; requires more setup." },
+          { id: "B", label: "PAT", tradeoffs: "Simpler; weaker rotation story." },
+        ],
+        recommendation: "A",
+        recommendationRationale: "Initial requirement implied multi-user; OAuth fits better.",
+        continueWithDefault: true,
+      };
+
+      await taskTool!.handler({
+        projectDir: base,
+        taskId: "T01",
+        sliceId: "S01",
+        milestoneId: "M001",
+        oneLiner: "Completed task with escalation",
+        narrative: "Did the work but flagged an ambiguity",
+        verification: "npm test",
+        escalation: escalationPayload,
+        verificationEvidence: [
+          { command: "npm test", exitCode: 0, verdict: "pass", durationMs: 1234 },
+        ],
+      });
+
+      assert.ok(existsSync(capturePath), "mock executor should have written captured args to disk");
+      const captured = JSON.parse(readFileSync(capturePath, "utf-8"));
+
+      // The handler resolves projectDir via realpathSync (security/symlink check),
+      // so on macOS where /var symlinks to /private/var, the captured path will
+      // be the realpath form. Normalize both sides.
+      assert.equal(captured.projectDir, realpathSync(base), "projectDir should be passed as second arg");
+      assert.deepEqual(
+        captured.params.escalation,
+        escalationPayload,
+        "escalation payload must reach the executor verbatim — regression guard for the destructure-rebuild bug class (#4477 review)",
+      );
+      // Spot-check a couple of other fields to ensure the spread pattern
+      // doesn't accidentally exclude the rest while including escalation.
+      assert.equal(captured.params.taskId, "T01", "taskId must be forwarded");
+      assert.equal(captured.params.milestoneId, "M001", "milestoneId must be forwarded");
+      assert.deepEqual(
+        captured.params.verificationEvidence,
+        [{ command: "npm test", exitCode: 0, verdict: "pass", durationMs: 1234 }],
+        "verificationEvidence must be forwarded (existing field)",
+      );
+      // Ensure no projectDir leak into params (it should be the second arg only).
+      assert.equal(
+        captured.params.projectDir,
+        undefined,
+        "projectDir must NOT appear in params — it's stripped via the spread destructure",
+      );
+    } finally {
+      if (prevModule === undefined) {
+        delete process.env.GSD_WORKFLOW_EXECUTORS_MODULE;
+      } else {
+        process.env.GSD_WORKFLOW_EXECUTORS_MODULE = prevModule;
+      }
+      if (prevCapture === undefined) {
+        delete process.env.GSD_TEST_TASK_COMPLETE_CAPTURE_PATH;
+      } else {
+        process.env.GSD_TEST_TASK_COMPLETE_CAPTURE_PATH = prevCapture;
+      }
+      cleanup(base);
+    }
+  });
+
   it("gsd_complete_task alias delegates to gsd_task_complete behavior", async () => {
     const base = makeTmpBase();
     try {
@@ -582,6 +712,91 @@ describe("workflow MCP tools", () => {
     }
   });
 
+  it("gsd_plan_milestone rejects a full slice with missing heavy fields via a behavioral round-trip", async () => {
+    // Behavioral guard for the full-vs-sketch conditional. The original
+    // regression (invisible "required unless isSketch" requirement) is
+    // surfaced to users through two distinct runtime channels:
+    //   1. A parse-time rejection when the tool is called with empty heavy
+    //      fields on a non-sketch slice (no isSketch=true).
+    //   2. An acceptance when isSketch=true + sketchScope is supplied and
+    //      heavy fields are omitted.
+    // Both arms are exercised below against the live handler — any schema
+    // refactor that preserves the user-observable contract (rejection +
+    // acceptance) passes, and any refactor that breaks the contract
+    // fails, regardless of whether internal `.describe()` prose changes.
+    const base = makeTmpBase();
+    try {
+      const server = makeMockServer();
+      registerWorkflowTools(server as any);
+      const milestoneTool = server.tools.find((t) => t.name === "gsd_plan_milestone");
+      assert.ok(milestoneTool, "milestone planning tool should be registered");
+
+      // 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);
+      for (const field of ["successCriteria", "proofLevel", "integrationClosure", "observabilityImpact"]) {
+        assert.ok(
+          fullMsg.includes(field),
+          `rejection must name ${field} so agents can recover without a second round-trip; got: ${fullMsg}`,
+        );
+      }
+
+      // Arm 2: sketch slice (isSketch=true + sketchScope) with heavy fields
+      // omitted must be accepted — proving the conditional is live. Assert
+      // success directly rather than just checking a thrown message omits
+      // the heavy-field names: a generic failure would otherwise silently
+      // pass this arm.
+      const sketchResult = await milestoneTool!.handler({
+        projectDir: base,
+        milestoneId: "M002",
+        title: "Sketch slice path",
+        vision: "Behavioral test for isSketch conditional.",
+        slices: [
+          {
+            sliceId: "S01",
+            title: "Sketch slice",
+            risk: "medium",
+            depends: [],
+            demo: "Demo.",
+            goal: "Goal.",
+            isSketch: true,
+            sketchScope: "Two-sentence scope. Boundary defined.",
+          },
+        ],
+      });
+      assert.match(
+        (sketchResult as any).content[0].text as string,
+        /Planned milestone M002/,
+        "sketch slice with isSketch=true must be accepted by the handler",
+      );
+    } finally {
+      cleanup(base);
+    }
+  });
+
   it("gsd_plan_milestone requires sketchScope when isSketch=true and skips heavy fields", async () => {
     const base = makeTmpBase();
     try {
@@ -1237,6 +1452,21 @@ describe("workflow MCP tools", () => {
         findings: "No new attack surface was introduced.",
       });
       assert.match((gateResult as any).content[0].text as string, /Gate Q3 result saved/);
+      // #4472: executor `details` must be adapted to MCP `structuredContent`
+      // so it survives the protocol transport intact. Asserting property
+      // *absence* rather than `=== undefined` so a future regression that
+      // explicitly sets `details: undefined` (rather than removing it) still
+      // fails this contract test.
+      assert.equal(
+        Object.prototype.hasOwnProperty.call(gateResult, "details"),
+        false,
+        "executor `details` field must be stripped from MCP tool result",
+      );
+      assert.deepEqual(
+        (gateResult as any).structuredContent,
+        { operation: "save_gate_result", gateId: "Q3", verdict: "pass" },
+        "executor details must be forwarded on the MCP `structuredContent` channel",
+      );
       const gateRows = _getAdapter()!.prepare(
         "SELECT status, verdict, rationale FROM quality_gates WHERE milestone_id = ? AND slice_id = ? AND gate_id = ?",
       ).all("M006", "S06", "Q3") as Array<Record<string, unknown>>;

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

@@ -599,6 +599,12 @@ export const WORKFLOW_TOOL_NAMES = [
   "gsd_complete_task",
   "gsd_milestone_status",
   "gsd_journal_query",
+  // ADR-013 step 3: memory-store tools exposed to external MCP clients.
+  // gsd_memory_graph is namespaced to avoid collision with the existing
+  // gsd_graph tool (project knowledge graph from .gsd/ artifacts).
+  "gsd_capture_thought",
+  "gsd_memory_query",
+  "gsd_memory_graph",
 ] as const;
 
 const DEFAULT_WORKFLOW_OP_TIMEOUT_MS = 5 * 60 * 1000;
@@ -611,6 +617,51 @@ function getWorkflowOpTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
   return parsed; // 0 disables the timeout
 }
 
+/**
+ * Adapt an executor `ToolExecutionResult` ({ content, details?, isError? }) to
+ * the MCP `CallToolResult` shape ({ content, structuredContent?, isError? }).
+ *
+ * MCP transports (including stdio) only serialize fields declared in the
+ * protocol, so a non-standard `details` field is silently dropped over the
+ * wire. Mirroring it into `structuredContent` — the protocol's supported
+ * channel for structured tool payloads — preserves the data for clients that
+ * render from it (e.g. the save_gate_result renderer that reads gateId /
+ * verdict). See #4472.
+ *
+ * Discard policy for non-plain-object `details`: the `isPlainObject` guard
+ * accepts the canonical case (a record literal) and intentionally drops bare
+ * primitives (string, number, boolean), bare arrays, and class instances /
+ * Date objects. This is deliberate — MCP `structuredContent` is specified as
+ * a JSON object; non-object payloads can't round-trip cleanly. No current
+ * executor returns a non-object `details`, so this never fires in practice.
+ * Future executors needing to return a primitive should wrap it
+ * (`details: { value: 42 }`) rather than relying on the discard.
+ */
+function adaptExecutorResult(result: unknown): unknown {
+  if (!result || typeof result !== "object") return result;
+  const r = result as Record<string, unknown>;
+  if (!("details" in r)) return result;
+  const { details, ...rest } = r;
+  return isPlainObject(details) ? { ...rest, structuredContent: details } : rest;
+}
+
+/**
+ * Strict plain-object guard. True only for object literals and
+ * `Object.create(null)` — not for `Date`, `URL`, `Map`, `Set`, class instances,
+ * or arrays. Used to gate `structuredContent` forwarding so the MCP transport
+ * receives only true JSON objects (the protocol contract).
+ *
+ * Mirrored in `src/mcp-server.ts` for the agent-tool registry path's
+ * structured-content gate. Keep both copies in sync if the contract definition
+ * needs to evolve. See #4477 review.
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype;
+}
+
 async function runSerializedWorkflowOperation<T>(fn: () => Promise<T>): Promise<T> {
   // The shared DB adapter and workflow log base path are process-global, so
   // workflow MCP mutations must not overlap within a single server process.
@@ -703,39 +754,15 @@ async function handleTaskComplete(
   args: Omit<z.infer<typeof taskCompleteSchema>, "projectDir">,
 ): Promise<unknown> {
   await enforceWorkflowWriteGate("gsd_task_complete", projectDir, args.milestoneId);
-  const {
-    taskId,
-    sliceId,
-    milestoneId,
-    oneLiner,
-    narrative,
-    verification,
-    deviations,
-    knownIssues,
-    keyFiles,
-    keyDecisions,
-    blockerDiscovered,
-    verificationEvidence,
-  } = args;
   const { executeTaskComplete } = await getWorkflowToolExecutors();
-  return runSerializedWorkflowOperation(() =>
-    executeTaskComplete(
-      {
-        taskId,
-        sliceId,
-        milestoneId,
-        oneLiner,
-        narrative,
-        verification,
-        deviations,
-        knownIssues,
-        keyFiles,
-        keyDecisions,
-        blockerDiscovered,
-        verificationEvidence,
-      },
-      projectDir,
-    ),
+  // Pass `args` through directly rather than destructure-then-rebuild. The
+  // previous implementation re-listed each field, which silently dropped
+  // schema fields that weren't in the rebuild list (e.g., ADR-011's
+  // `escalation` payload). The destructure-then-rebuild pattern is the bug
+  // class; matching the spread shape used by sibling handlers (handleSliceComplete,
+  // handleReplanSlice) eliminates the recurrence risk by construction.
+  return adaptExecutorResult(
+    await runSerializedWorkflowOperation(() => executeTaskComplete(args, projectDir)),
   );
 }
 
@@ -746,7 +773,9 @@ async function handleSliceComplete(
   await enforceWorkflowWriteGate("gsd_slice_complete", projectDir, args.milestoneId);
   const { executeSliceComplete } = await getWorkflowToolExecutors();
   const { projectDir: _projectDir, ...params } = args;
-  return runSerializedWorkflowOperation(() => executeSliceComplete(params, projectDir));
+  return adaptExecutorResult(
+    await runSerializedWorkflowOperation(() => executeSliceComplete(params, projectDir)),
+  );
 }
 
 async function handleReplanSlice(
@@ -756,7 +785,9 @@ async function handleReplanSlice(
   await enforceWorkflowWriteGate("gsd_replan_slice", projectDir, args.milestoneId);
   const { executeReplanSlice } = await getWorkflowToolExecutors();
   const { projectDir: _projectDir, ...params } = args;
-  return runSerializedWorkflowOperation(() => executeReplanSlice(params, projectDir));
+  return adaptExecutorResult(
+    await runSerializedWorkflowOperation(() => executeReplanSlice(params, projectDir)),
+  );
 }
 
 async function handleCompleteMilestone(
@@ -766,7 +797,9 @@ async function handleCompleteMilestone(
   await enforceWorkflowWriteGate("gsd_complete_milestone", projectDir, args.milestoneId);
   const { executeCompleteMilestone } = await getWorkflowToolExecutors();
   const { projectDir: _projectDir, ...params } = args;
-  return runSerializedWorkflowOperation(() => executeCompleteMilestone(params, projectDir));
+  return adaptExecutorResult(
+    await runSerializedWorkflowOperation(() => executeCompleteMilestone(params, projectDir)),
+  );
 }
 
 async function handleValidateMilestone(
@@ -776,7 +809,9 @@ async function handleValidateMilestone(
   await enforceWorkflowWriteGate("gsd_validate_milestone", projectDir, args.milestoneId);
   const { executeValidateMilestone } = await getWorkflowToolExecutors();
   const { projectDir: _projectDir, ...params } = args;
-  return runSerializedWorkflowOperation(() => executeValidateMilestone(params, projectDir));
+  return adaptExecutorResult(
+    await runSerializedWorkflowOperation(() => executeValidateMilestone(params, projectDir)),
+  );
 }
 
 async function handleReassessRoadmap(
@@ -786,7 +821,9 @@ async function handleReassessRoadmap(
   await enforceWorkflowWriteGate("gsd_reassess_roadmap", projectDir, args.milestoneId);
   const { executeReassessRoadmap } = await getWorkflowToolExecutors();
   const { projectDir: _projectDir, ...params } = args;
-  return runSerializedWorkflowOperation(() => executeReassessRoadmap(params, projectDir));
+  return adaptExecutorResult(
+    await runSerializedWorkflowOperation(() => executeReassessRoadmap(params, projectDir)),
+  );
 }
 
 async function handleSaveGateResult(
@@ -796,7 +833,9 @@ async function handleSaveGateResult(
   await enforceWorkflowWriteGate("gsd_save_gate_result", projectDir, args.milestoneId);
   const { executeSaveGateResult } = await getWorkflowToolExecutors();
   const { projectDir: _projectDir, ...params } = args;
-  return runSerializedWorkflowOperation(() => executeSaveGateResult(params, projectDir));
+  return adaptExecutorResult(
+    await runSerializedWorkflowOperation(() => executeSaveGateResult(params, projectDir)),
+  );
 }
 
 async function ensureMilestoneDbRow(milestoneId: string): Promise<void> {
@@ -836,6 +875,17 @@ const nonEmptyStringArray = (field: string) =>
 // empty/whitespace fields at parse time. Without this, MCP callers pass "" for
 // the heavy planning fields, Zod accepts it, and the executor rejects one
 // field per call — forcing the agent into a retry loop to discover every gap.
+//
+// #4759 follow-up: the four heavy fields are Zod-optional because sketch
+// slices (isSketch=true) legitimately omit them, but they are REQUIRED for
+// every other slice. The conditional requirement is invisible in the JSON
+// Schema `required` array, so callers can only discover it from the
+// descriptions or by hitting the runtime superRefine below. The `.describe()`
+// calls below make that contract unmistakable in the tool schema sent to
+// agents; the superRefine enforces it at parse time.
+const HEAVY_FIELD_DESCRIBE = (field: string) =>
+  `${field} for this slice. REQUIRED unless isSketch=true (sketch slices defer this to refine-slice).`;
+
 const planMilestoneSliceSchema = z.object({
   sliceId: nonEmptyString("sliceId"),
   title: nonEmptyString("title"),
@@ -844,14 +894,16 @@ const planMilestoneSliceSchema = z.object({
   demo: nonEmptyString("demo"),
   goal: nonEmptyString("goal"),
   // ADR-011: heavy planning fields are optional for sketch slices; required for full slices.
-  successCriteria: z.string().optional(),
-  proofLevel: z.string().optional(),
-  integrationClosure: z.string().optional(),
-  observabilityImpact: z.string().optional(),
+  successCriteria: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("successCriteria")),
+  proofLevel: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("proofLevel")),
+  integrationClosure: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("integrationClosure")),
+  observabilityImpact: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("observabilityImpact")),
   // ADR-011 sketch-then-refine fields.
-  isSketch: z.boolean().optional().describe("ADR-011: true marks this slice as a sketch awaiting refine-slice expansion"),
+  isSketch: z.boolean().optional().describe("ADR-011: true marks this slice as a sketch awaiting refine-slice expansion. When true, successCriteria/proofLevel/integrationClosure/observabilityImpact may be omitted and sketchScope becomes required."),
   sketchScope: z.string().optional().describe("ADR-011: 2-3 sentence scope boundary, required when isSketch=true"),
-}).superRefine((slice, ctx) => {
+}).describe(
+  "Planned slice. For full slices (isSketch omitted or false): successCriteria, proofLevel, integrationClosure, and observabilityImpact are all required. For sketch slices (isSketch=true): those four fields may be omitted, but sketchScope is required.",
+).superRefine((slice, ctx) => {
   if (slice.isSketch === true) {
     if (typeof slice.sketchScope !== "string" || slice.sketchScope.trim().length === 0) {
       ctx.addIssue({
@@ -1378,7 +1430,9 @@ export function registerWorkflowTools(server: McpToolServer): void {
       const { projectDir, ...params } = parsed;
       await enforceWorkflowWriteGate("gsd_plan_milestone", projectDir, params.milestoneId);
       const { executePlanMilestone } = await getWorkflowToolExecutors();
-      return runSerializedWorkflowOperation(() => executePlanMilestone(params, projectDir));
+      return adaptExecutorResult(
+        await runSerializedWorkflowOperation(() => executePlanMilestone(params, projectDir)),
+      );
     },
   );
 
@@ -1391,7 +1445,9 @@ export function registerWorkflowTools(server: McpToolServer): void {
       const { projectDir, ...params } = parsed;
       await enforceWorkflowWriteGate("gsd_plan_slice", projectDir, params.milestoneId);
       const { executePlanSlice } = await getWorkflowToolExecutors();
-      return runSerializedWorkflowOperation(() => executePlanSlice(params, projectDir));
+      return adaptExecutorResult(
+        await runSerializedWorkflowOperation(() => executePlanSlice(params, projectDir)),
+      );
     },
   );
 
@@ -1592,8 +1648,10 @@ export function registerWorkflowTools(server: McpToolServer): void {
           `artifact_type must be one of: ${supportedArtifactTypes.join(", ")}`,
         );
       }
-      return runSerializedWorkflowOperation(() =>
-        executors.executeSummarySave({ milestone_id, slice_id, task_id, artifact_type, content }, projectDir),
+      return adaptExecutorResult(
+        await runSerializedWorkflowOperation(() =>
+          executors.executeSummarySave({ milestone_id, slice_id, task_id, artifact_type, content }, projectDir),
+        ),
       );
     },
   );
@@ -1630,7 +1688,9 @@ export function registerWorkflowTools(server: McpToolServer): void {
       // during pending-gate or queue-mode states.
       const { projectDir, milestoneId } = parseWorkflowArgs(milestoneStatusSchema, args);
       const { executeMilestoneStatus } = await getWorkflowToolExecutors();
-      return runSerializedWorkflowOperation(() => executeMilestoneStatus({ milestoneId }, projectDir));
+      return adaptExecutorResult(
+        await runSerializedWorkflowOperation(() => executeMilestoneStatus({ milestoneId }, projectDir)),
+      );
     },
   );
 
@@ -1648,4 +1708,129 @@ export function registerWorkflowTools(server: McpToolServer): void {
       return { content: [{ type: "text" as const, text: JSON.stringify(entries, null, 2) }] };
     },
   );
+
+  // ─── ADR-013 step 3 — memory-store tools for external MCP clients ────────
+  //
+  // The same three tools the LLM sees in-process as `capture_thought`,
+  // `memory_query`, and `gsd_graph` (the memory variant). MCP exposes them
+  // under the gsd_* prefix and renames the memory graph to gsd_memory_graph
+  // to avoid collision with the project knowledge graph tool registered as
+  // `gsd_graph` in server.ts.
+
+  const MEMORY_CATEGORY = z.enum([
+    "architecture",
+    "convention",
+    "gotcha",
+    "preference",
+    "environment",
+    "pattern",
+  ]);
+
+  const captureThoughtSchema = z.object({
+    projectDir: z.string().optional(),
+    category: MEMORY_CATEGORY,
+    // Reject empty / whitespace-only content at the schema layer so the LLM
+    // never produces a memory row with no searchable text.
+    content: z.string().trim().min(1, "content must be a non-empty trimmed string"),
+    confidence: z.number().min(0.1).max(0.99).optional(),
+    tags: z.array(z.string()).optional(),
+    scope: z.string().optional(),
+    structuredFields: z.record(z.string(), z.unknown()).optional(),
+  });
+  const captureThoughtParams = {
+    projectDir: z.string().optional().describe("Absolute path to the project directory (defaults to MCP server cwd)"),
+    category: MEMORY_CATEGORY.describe("Memory category"),
+    content: z.string().describe("Memory text (1-3 sentences, no secrets)"),
+    confidence: z.number().min(0.1).max(0.99).optional().describe("0.1-0.99, default 0.8"),
+    tags: z.array(z.string()).optional().describe("Free-form tags"),
+    scope: z.string().optional().describe("Scope name; defaults to 'project'"),
+    structuredFields: z.record(z.string(), z.unknown()).optional().describe("ADR-013 structured payload (e.g. decision fields)"),
+  };
+
+  server.tool(
+    "gsd_capture_thought",
+    "Record a durable project insight into the GSD memory store. Categories: architecture, convention, gotcha, preference, environment, pattern. Mirrors the in-process capture_thought tool for external MCP clients.",
+    captureThoughtParams,
+    async (args: Record<string, unknown>) => {
+      const { projectDir, ...params } = parseWorkflowArgs(captureThoughtSchema, args);
+      await enforceWorkflowWriteGate("gsd_capture_thought", projectDir);
+      return runSerializedWorkflowDbOperation(projectDir, async () => {
+        const { executeMemoryCapture } = await importLocalModule<any>(
+          "../../../src/resources/extensions/gsd/tools/memory-tools.js",
+        );
+        return executeMemoryCapture(params);
+      });
+    },
+  );
+
+  const memoryQuerySchema = z.object({
+    projectDir: z.string().optional(),
+    // Match the documented "2+ char terms" contract in the in-process
+    // memory_query tool — reject sub-2-char queries at the schema layer.
+    query: z.string().trim().min(2, "query must be at least 2 characters"),
+    k: z.number().int().min(1).max(50).optional(),
+    category: MEMORY_CATEGORY.optional(),
+    scope: z.string().optional(),
+    tag: z.string().optional(),
+    include_superseded: z.boolean().optional(),
+    reinforce_hits: z.boolean().optional(),
+  });
+  const memoryQueryParams = {
+    projectDir: z.string().optional().describe("Absolute path to the project directory (defaults to MCP server cwd)"),
+    query: z.string().describe("Keyword query (2+ char terms)"),
+    k: z.number().int().min(1).max(50).optional().describe("Max results (default 10, max 50)"),
+    category: MEMORY_CATEGORY.optional().describe("Restrict to a single category"),
+    scope: z.string().optional().describe("Only include memories with this scope"),
+    tag: z.string().optional().describe("Only include memories tagged with this value"),
+    include_superseded: z.boolean().optional().describe("Include superseded memories (default false)"),
+    reinforce_hits: z.boolean().optional().describe("Increment hit_count on returned memories (default false)"),
+  };
+
+  server.tool(
+    "gsd_memory_query",
+    "Search the GSD memory store by keyword. Returns ranked memories with id, category, content, confidence, scope, and tags. Mirrors the in-process memory_query tool for external MCP clients.",
+    memoryQueryParams,
+    async (args: Record<string, unknown>) => {
+      const { projectDir, ...params } = parseWorkflowArgs(memoryQuerySchema, args);
+      return runSerializedWorkflowDbOperation(projectDir, async () => {
+        const { executeMemoryQuery } = await importLocalModule<any>(
+          "../../../src/resources/extensions/gsd/tools/memory-tools.js",
+        );
+        return executeMemoryQuery(params);
+      });
+    },
+  );
+
+  const memoryGraphSchema = z.object({
+    projectDir: z.string().optional(),
+    mode: z.enum(["build", "query"]),
+    memoryId: z.string().optional(),
+    depth: z.number().int().min(0).max(5).optional(),
+    rel: z.enum(["related_to", "depends_on", "contradicts", "elaborates", "supersedes"]).optional(),
+  }).refine(
+    (val) => val.mode !== "query" || (typeof val.memoryId === "string" && val.memoryId.trim().length > 0),
+    { message: "memoryId is required and must be non-empty when mode=query", path: ["memoryId"] },
+  );
+  const memoryGraphParams = {
+    projectDir: z.string().optional().describe("Absolute path to the project directory (defaults to MCP server cwd)"),
+    mode: z.enum(["build", "query"]).describe("build = recompute graph (placeholder), query = inspect edges"),
+    memoryId: z.string().optional().describe("Memory ID (required when mode=query)"),
+    depth: z.number().int().min(0).max(5).optional().describe("Hops to traverse (0-5, default 1)"),
+    rel: z.enum(["related_to", "depends_on", "contradicts", "elaborates", "supersedes"]).optional().describe("Only include edges with this relation type"),
+  };
+
+  server.tool(
+    "gsd_memory_graph",
+    "Inspect the relationship graph between memories. mode=query walks edges from a given memoryId. mode=build is a placeholder reserved for future graph rebuilds. Distinct from gsd_graph (project knowledge graph) — see ADR-013.",
+    memoryGraphParams,
+    async (args: Record<string, unknown>) => {
+      const { projectDir, ...params } = parseWorkflowArgs(memoryGraphSchema, args);
+      return runSerializedWorkflowDbOperation(projectDir, async () => {
+        const { executeGsdGraph } = await importLocalModule<any>(
+          "../../../src/resources/extensions/gsd/tools/memory-tools.js",
+        );
+        return executeGsdGraph(params);
+      });
+    },
+  );
 }

package/packages/mcp-server/tsconfig.test.json

@@ -0,0 +1,19 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": false,
+    "declarationMap": false,
+    "incremental": false,
+    "outDir": "./dist"
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.d.ts",
+    "src/**/*.d.ts",
+    "src/workflow-tools.test.ts"
+  ]
+}