gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.2ff77b0ce

package/packages/mcp-server/src/env-writer.test.ts

@@ -1,5 +1,4 @@
 // @gsd-build/mcp-server — Tests for env-writer utilities
-// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 
 import { describe, it, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
@@ -12,6 +11,7 @@ import {
   detectDestination,
   writeEnvKey,
   applySecrets,
+  isSecuritySensitiveEnvKey,
   isSafeEnvVarKey,
   isSupportedDeploymentEnvironment,
   resolveProjectEnvFilePath,
@@ -295,6 +295,41 @@ describe('applySecrets', () => {
     }
   });
 
+  it('rejects invalid dotenv keys before writing or hydrating', async () => {
+    const tmp = makeTempDir('apply-invalid');
+    const envPath = join(tmp, '.env');
+    try {
+      const { applied, errors } = await applySecrets(
+        [{ key: 'BAD-KEY', value: 'val-a' }],
+        'dotenv',
+        { envFilePath: envPath },
+      );
+      assert.deepStrictEqual(applied, []);
+      assert.deepStrictEqual(errors, ['BAD-KEY: invalid environment variable name']);
+      assert.throws(() => readFileSync(envPath, 'utf8'), /ENOENT/);
+      assert.equal(process.env['BAD-KEY'], undefined);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects security-sensitive dotenv keys case-insensitively', async () => {
+    const tmp = makeTempDir('apply-sensitive');
+    const envPath = join(tmp, '.env');
+    try {
+      const { applied, errors } = await applySecrets(
+        [{ key: 'path', value: 'malicious-bin' }],
+        'dotenv',
+        { envFilePath: envPath },
+      );
+      assert.deepStrictEqual(applied, []);
+      assert.deepStrictEqual(errors, ['path: refusing to set MCP server runtime variable via secure_env_collect']);
+      assert.throws(() => readFileSync(envPath, 'utf8'), /ENOENT/);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
   it('returns errors for invalid vercel environment', async () => {
     const tmp = makeTempDir('apply');
     try {
@@ -313,6 +348,38 @@ describe('applySecrets', () => {
       rmSync(tmp, { recursive: true, force: true });
     }
   });
+
+  it('passes remote destination secrets on stdin instead of process arguments', async () => {
+    const tmp = makeTempDir('apply-remote-stdin');
+    const calls: Array<{ cmd: string; args: string[]; opts?: { stdin?: string } }> = [];
+    try {
+      const { applied, errors } = await applySecrets(
+        [{ key: 'REMOTE_SECRET', value: 'super-secret-value' }],
+        'vercel',
+        {
+          envFilePath: join(tmp, '.env'),
+          environment: 'preview',
+          execFn: async (cmd, args, opts) => {
+            calls.push({ cmd, args, opts });
+            return { code: 0, stderr: '' };
+          },
+        },
+      );
+
+      assert.deepStrictEqual(applied, ['REMOTE_SECRET']);
+      assert.deepStrictEqual(errors, []);
+      assert.deepStrictEqual(calls, [
+        {
+          cmd: 'vercel',
+          args: ['env', 'add', 'REMOTE_SECRET', 'preview'],
+          opts: { stdin: 'super-secret-value' },
+        },
+      ]);
+      assert.ok(!calls[0].args.some((arg) => arg.includes('super-secret-value')));
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -334,6 +401,14 @@ describe('isSafeEnvVarKey', () => {
   });
 });
 
+describe('isSecuritySensitiveEnvKey', () => {
+  it('matches sensitive keys case-insensitively', () => {
+    assert.ok(isSecuritySensitiveEnvKey('PATH'));
+    assert.ok(isSecuritySensitiveEnvKey('path'));
+    assert.ok(isSecuritySensitiveEnvKey('Node_Options'));
+  });
+});
+
 describe('isSupportedDeploymentEnvironment', () => {
   it('accepts valid environments', () => {
     assert.ok(isSupportedDeploymentEnvironment('development'));

package/packages/mcp-server/src/env-writer.ts

@@ -1,5 +1,4 @@
 // @gsd-build/mcp-server — Environment variable write utilities
-// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 //
 // Shared helpers for writing env vars to .env files, detecting project
 // destinations, and checking existing keys. Used by secure_env_collect
@@ -141,6 +140,29 @@ export function isSafeEnvVarKey(key: string): boolean {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
 }
 
+/**
+ * Keys that influence the MCP server's own runtime — module loading, project
+ * sandbox, CLI resolution. Allowing the LLM to set these via secure_env_collect
+ * would let a misbehaving caller swap the workflow executor module mid-session
+ * (RCE chain) or escape the project sandbox. We refuse to write or hydrate
+ * these keys even when isSafeEnvVarKey() would otherwise accept them.
+ */
+const SECURITY_SENSITIVE_KEYS = new Set<string>([
+  "GSD_WORKFLOW_EXECUTORS_MODULE",
+  "GSD_WORKFLOW_WRITE_GATE_MODULE",
+  "GSD_WORKFLOW_PROJECT_ROOT",
+  "GSD_CLI_PATH",
+  "NODE_OPTIONS",
+  "NODE_PATH",
+  "PATH",
+  "LD_PRELOAD",
+  "DYLD_INSERT_LIBRARIES",
+]);
+
+export function isSecuritySensitiveEnvKey(key: string): boolean {
+  return SECURITY_SENSITIVE_KEYS.has(key.toUpperCase());
+}
+
 export function isSupportedDeploymentEnvironment(env: string): boolean {
   return env === "development" || env === "preview" || env === "production";
 }
@@ -188,6 +210,10 @@ interface ApplyResult {
   errors: string[];
 }
 
+interface ExecOptions {
+  stdin?: string;
+}
+
 /**
  * Apply collected secrets to the target destination.
  * Dotenv writes are handled directly; vercel/convex shell out via execFn.
@@ -198,7 +224,7 @@ export async function applySecrets(
   opts: {
     envFilePath: string;
     environment?: string;
-    execFn?: (cmd: string, args: string[]) => Promise<{ code: number; stderr: string }>;
+    execFn?: (cmd: string, args: string[], opts?: ExecOptions) => Promise<{ code: number; stderr: string }>;
   },
 ): Promise<ApplyResult> {
   const applied: string[] = [];
@@ -206,10 +232,20 @@ export async function applySecrets(
 
   if (destination === "dotenv") {
     for (const { key, value } of provided) {
+      if (!isSafeEnvVarKey(key)) {
+        errors.push(`${key}: invalid environment variable name`);
+        continue;
+      }
+      if (isSecuritySensitiveEnvKey(key)) {
+        errors.push(`${key}: refusing to set MCP server runtime variable via secure_env_collect`);
+        continue;
+      }
       try {
         await writeEnvKey(opts.envFilePath, key, value);
         applied.push(key);
-        // Hydrate process.env so the current session sees the new value
+        // Hydrate process.env so the current session sees the new value.
+        // Sensitive keys are excluded above so a malicious caller cannot
+        // swap our module-loading or sandbox configuration mid-session.
         process.env[key] = value;
       } catch (err: unknown) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -229,18 +265,21 @@ export async function applySecrets(
         errors.push(`${key}: invalid environment variable name`);
         continue;
       }
-      const cmd = destination === "vercel"
-        ? `printf %s ${shellEscapeSingle(value)} | vercel env add ${key} ${env}`
-        : "";
+      if (isSecuritySensitiveEnvKey(key)) {
+        errors.push(`${key}: refusing to set MCP server runtime variable via secure_env_collect`);
+        continue;
+      }
       try {
         const result = destination === "vercel"
-          ? await opts.execFn("sh", ["-c", cmd])
-          : await opts.execFn("npx", ["convex", "env", "set", key, value]);
+          ? await opts.execFn("vercel", ["env", "add", key, env], { stdin: value })
+          : await opts.execFn("npx", ["convex", "env", "set", key], { stdin: value });
         if (result.code !== 0) {
           errors.push(`${key}: ${result.stderr.slice(0, 200)}`);
         } else {
           applied.push(key);
-          process.env[key] = value;
+          // Do NOT hydrate process.env after pushing to a remote destination:
+          // no in-process reader needs a freshly-pushed remote secret, and
+          // every spawned child would inherit the plaintext value.
         }
       } catch (err: unknown) {
         const msg = err instanceof Error ? err.message : String(err);

package/packages/mcp-server/src/import-candidates.test.ts

@@ -33,16 +33,21 @@ describe("_buildImportCandidates", () => {
     );
   });
 
-  it("returns original path first", () => {
+  it("returns source TypeScript before stale JavaScript fallbacks", () => {
     const input = "../../../src/resources/extensions/gsd/db-writer.js";
     const candidates = _buildImportCandidates(input);
-    assert.equal(candidates[0], input, "first candidate should be the original path");
+    assert.deepEqual(candidates, [
+      "../../../src/resources/extensions/gsd/db-writer.ts",
+      "../../../src/resources/extensions/gsd/db-writer.js",
+      "../../../dist/resources/extensions/gsd/db-writer.ts",
+      "../../../dist/resources/extensions/gsd/db-writer.js",
+    ]);
   });
 
   it("handles paths without src/ or dist/ gracefully", () => {
     const candidates = _buildImportCandidates("./local-module.js");
     assert.equal(candidates.length, 2, "should have original + .ts variant only");
-    assert.equal(candidates[0], "./local-module.js");
-    assert.equal(candidates[1], "./local-module.ts");
+    assert.equal(candidates[0], "./local-module.ts");
+    assert.equal(candidates[1], "./local-module.js");
   });
 });

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

@@ -12,11 +12,14 @@
 
 import { describe, it, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { resolve } from 'node:path';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, join, resolve } from 'node:path';
 import { EventEmitter } from 'node:events';
 
 import { SessionManager } from './session-manager.js';
 import {
+  askUserQuestionsHandler,
   buildAskUserQuestionsElicitRequest,
   createMcpServer,
   formatAskUserQuestionsElicitResult,
@@ -563,6 +566,7 @@ describe('SessionManager', () => {
 describe('SessionManager.resolveCLIPath', () => {
   const originalGsdPath = process.env['GSD_CLI_PATH'];
   const originalPath = process.env['PATH'];
+  const originalPathTitle = process.env['Path'];
 
   afterEach(() => {
     if (originalGsdPath !== undefined) {
@@ -572,6 +576,13 @@ describe('SessionManager.resolveCLIPath', () => {
     }
     if (originalPath !== undefined) {
       process.env['PATH'] = originalPath;
+    } else {
+      delete process.env['PATH'];
+    }
+    if (originalPathTitle !== undefined) {
+      process.env['Path'] = originalPathTitle;
+    } else {
+      delete process.env['Path'];
     }
   });
 
@@ -581,8 +592,50 @@ describe('SessionManager.resolveCLIPath', () => {
     assert.equal(result, resolve('/custom/path/to/gsd'));
   });
 
-  it('throws when GSD_CLI_PATH not set and which fails', () => {
+  it('finds gsd on PATH without shelling out to which', () => {
     delete process.env['GSD_CLI_PATH'];
+    const tmp = mkdtempSync(join(tmpdir(), 'gsd-cli-path-'));
+    try {
+      const shimName = process.platform === 'win32' ? 'gsd.cmd' : 'gsd';
+      const shimPath = join(tmp, shimName);
+      writeFileSync(shimPath, '', 'utf8');
+      process.env['PATH'] = [tmp, originalPath].filter(Boolean).join(delimiter);
+
+      const resolvedPath = SessionManager.resolveCLIPath();
+      if (process.platform === 'win32') {
+        assert.equal(resolvedPath.toLowerCase(), resolve(shimPath).toLowerCase());
+      } else {
+        assert.equal(resolvedPath, resolve(shimPath));
+      }
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it('finds gsd when Windows exposes Path instead of PATH', () => {
+    delete process.env['GSD_CLI_PATH'];
+    delete process.env['PATH'];
+    const tmp = mkdtempSync(join(tmpdir(), 'gsd-cli-path-title-'));
+    try {
+      const shimName = process.platform === 'win32' ? 'gsd.cmd' : 'gsd';
+      const shimPath = join(tmp, shimName);
+      writeFileSync(shimPath, '', 'utf8');
+      process.env['Path'] = tmp;
+
+      const resolvedPath = SessionManager.resolveCLIPath();
+      if (process.platform === 'win32') {
+        assert.equal(resolvedPath.toLowerCase(), resolve(shimPath).toLowerCase());
+      } else {
+        assert.equal(resolvedPath, resolve(shimPath));
+      }
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it('throws when GSD_CLI_PATH not set and PATH lookup fails', () => {
+    delete process.env['GSD_CLI_PATH'];
+    delete process.env['Path'];
     process.env['PATH'] = '/nonexistent';
     assert.throws(
       () => SessionManager.resolveCLIPath(),
@@ -783,6 +836,147 @@ describe('createMcpServer tool registration', () => {
       }),
     );
   });
+
+  it('ask_user_questions returns local elicitation answers before trying remote', async () => {
+    const questions = [
+      {
+        id: 'depth_verification_M001',
+        header: 'Depth Check',
+        question: 'Did I capture the depth right?',
+        options: [
+          { label: 'Yes, you got it (Recommended)', description: 'Continue with the current summary.' },
+          { label: 'Not quite', description: 'I need to clarify the depth further.' },
+        ],
+      },
+    ];
+    let remoteCalls = 0;
+
+    const result = await askUserQuestionsHandler(questions, undefined, {
+      async elicitInput() {
+        return {
+          action: 'accept',
+          content: {
+            depth_verification_M001: 'Yes, you got it (Recommended)',
+          },
+        };
+      },
+      isRemoteConfigured() {
+        return true;
+      },
+      async tryRemoteQuestions() {
+        remoteCalls++;
+        return { content: [{ type: 'text', text: 'remote response' }] };
+      },
+    });
+
+    assert.equal(remoteCalls, 0);
+    assert.equal(
+      result.content[0]?.text,
+      JSON.stringify({
+        answers: {
+          depth_verification_M001: {
+            answers: ['Yes, you got it (Recommended)'],
+          },
+        },
+      }),
+    );
+  });
+
+  it('ask_user_questions falls back to remote when local elicitation is cancelled', async () => {
+    const questions = [
+      {
+        id: 'depth_verification_M001',
+        header: 'Depth Check',
+        question: 'Did I capture the depth right?',
+        options: [
+          { label: 'Yes, you got it (Recommended)', description: 'Continue with the current summary.' },
+          { label: 'Not quite', description: 'I need to clarify the depth further.' },
+        ],
+      },
+    ];
+    let remoteCalls = 0;
+    const signal = AbortSignal.abort();
+
+    const result = await askUserQuestionsHandler(questions, { signal }, {
+      async elicitInput() {
+        return { action: 'cancel' };
+      },
+      isRemoteConfigured() {
+        return true;
+      },
+      async tryRemoteQuestions(remoteQuestions, receivedSignal) {
+        remoteCalls++;
+        assert.equal(remoteQuestions, questions);
+        assert.equal(receivedSignal, signal);
+        return { content: [{ type: 'text', text: 'remote response' }] };
+      },
+    });
+
+    assert.equal(remoteCalls, 1);
+    assert.equal(result.content[0]?.text, 'remote response');
+  });
+
+  it('ask_user_questions falls back to remote when local elicitation is unavailable', async () => {
+    const questions = [
+      {
+        id: 'depth_verification_M001',
+        header: 'Depth Check',
+        question: 'Did I capture the depth right?',
+        options: [
+          { label: 'Yes, you got it (Recommended)', description: 'Continue with the current summary.' },
+          { label: 'Not quite', description: 'I need to clarify the depth further.' },
+        ],
+      },
+    ];
+    let remoteCalls = 0;
+
+    const result = await askUserQuestionsHandler(questions, undefined, {
+      async elicitInput() {
+        throw new Error('MCP host does not support elicitation');
+      },
+      isRemoteConfigured() {
+        return true;
+      },
+      async tryRemoteQuestions(remoteQuestions) {
+        remoteCalls++;
+        assert.equal(remoteQuestions, questions);
+        return { content: [{ type: 'text', text: 'remote response' }] };
+      },
+    });
+
+    assert.equal(remoteCalls, 1);
+    assert.equal(result.content[0]?.text, 'remote response');
+  });
+
+  it('ask_user_questions reports both local and remote errors when both paths fail', async () => {
+    const questions = [
+      {
+        id: 'depth_verification_M001',
+        header: 'Depth Check',
+        question: 'Did I capture the depth right?',
+        options: [
+          { label: 'Yes, you got it (Recommended)', description: 'Continue with the current summary.' },
+          { label: 'Not quite', description: 'I need to clarify the depth further.' },
+        ],
+      },
+    ];
+
+    const result = await askUserQuestionsHandler(questions, undefined, {
+      async elicitInput() {
+        throw new Error('ask_user_questions timed out after 10 minutes');
+      },
+      isRemoteConfigured() {
+        return true;
+      },
+      async tryRemoteQuestions() {
+        throw new Error('remote transport failed');
+      },
+    });
+
+    assert.equal('isError' in result && result.isError, true);
+    assert.match(result.content[0]?.text ?? '', /Local elicitation failed/);
+    assert.match(result.content[0]?.text ?? '', /remote transport failed/);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/packages/mcp-server/src/parse-workflow-args.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Regression tests for parseWorkflowArgs cwd handling:
+ *  - Refuses when projectDir resolves to $HOME (defense-in-depth against the
+ *    MCP server's process.cwd() falling back to home).
+ *  - Routes writes to a sole active auto-worktree when milestoneId is omitted.
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync, realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+
+import { _parseWorkflowArgsForTest } from "./workflow-tools.js";
+
+const minimalSchema = z.object({
+  projectDir: z.string().optional(),
+  milestoneId: z.string().optional(),
+});
+
+describe("parseWorkflowArgs $HOME guard", () => {
+  it("throws when projectDir resolves to the user's home directory", () => {
+    assert.throws(
+      () => _parseWorkflowArgsForTest(minimalSchema, { projectDir: homedir() }),
+      /home directory/i,
+    );
+  });
+});
+
+describe("parseWorkflowArgs sole-worktree fallback", () => {
+  it("routes writes to the lone auto-worktree when milestoneId is omitted", () => {
+    const project = realpathSync(mkdtempSync(join(tmpdir(), "gsd-mcp-wt-")));
+    try {
+      mkdirSync(join(project, ".gsd"), { recursive: true });
+      const wt = join(project, ".gsd", "worktrees", "M001");
+      mkdirSync(wt, { recursive: true });
+      writeFileSync(join(wt, ".git"), "gitdir: /fake/path/to/git\n");
+
+      const result = _parseWorkflowArgsForTest(minimalSchema, { projectDir: project });
+      assert.equal(result.projectDir, wt, "should re-route to the sole worktree");
+    } finally {
+      rmSync(project, { recursive: true, force: true });
+    }
+  });
+
+  it("stays at project root when multiple worktrees exist (ambiguous)", () => {
+    const project = realpathSync(mkdtempSync(join(tmpdir(), "gsd-mcp-wt-multi-")));
+    try {
+      mkdirSync(join(project, ".gsd"), { recursive: true });
+      for (const id of ["M001", "M002"]) {
+        const wt = join(project, ".gsd", "worktrees", id);
+        mkdirSync(wt, { recursive: true });
+        writeFileSync(join(wt, ".git"), "gitdir: /fake/git\n");
+      }
+
+      const result = _parseWorkflowArgsForTest(minimalSchema, { projectDir: project });
+      assert.equal(result.projectDir, project, "ambiguous → keep project root");
+    } finally {
+      rmSync(project, { recursive: true, force: true });
+    }
+  });
+
+  it("uses the explicit milestone worktree when milestoneId is provided", () => {
+    const project = realpathSync(mkdtempSync(join(tmpdir(), "gsd-mcp-wt-explicit-")));
+    try {
+      mkdirSync(join(project, ".gsd"), { recursive: true });
+      const wt = join(project, ".gsd", "worktrees", "M042");
+      mkdirSync(wt, { recursive: true });
+      writeFileSync(join(wt, ".git"), "gitdir: /fake/git\n");
+
+      const result = _parseWorkflowArgsForTest(minimalSchema, {
+        projectDir: project,
+        milestoneId: "M042",
+      });
+      assert.equal(result.projectDir, wt);
+    } finally {
+      rmSync(project, { recursive: true, force: true });
+    }
+  });
+});

package/packages/mcp-server/src/readers/graph.test.ts

@@ -1,5 +1,4 @@
 // GSD MCP Server — knowledge graph reader tests
-// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 
 import { describe, it, before, after, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
@@ -378,8 +377,12 @@ missing_artifacts: []
     const graph = await buildGraph(noLearningsProject);
     assert.ok(Array.isArray(graph.nodes));
     assert.equal(typeof graph.builtAt, 'string');
+    // Surprises are stored as nodes of type 'lesson' with id-prefix
+    // 'surprise:' (see graph.ts:442); the literal 'surprise' was never a
+    // member of NodeType, so the comparison was a silently-always-false
+    // tautology that triggered TS2367 under strict checks.
     const learningNodes = graph.nodes.filter(
-      (n) => n.type === 'decision' || n.type === 'lesson' || n.type === 'pattern' || n.type === 'surprise',
+      (n) => n.type === 'decision' || n.type === 'lesson' || n.type === 'pattern',
     );
     assert.equal(
       learningNodes.length,

package/packages/mcp-server/src/readers/graph.ts

@@ -13,8 +13,15 @@
  */
 
 import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { resolveGsdRoot, findMilestoneIds, resolveMilestoneDir, findSliceIds, resolveSliceDir } from './paths.js';
+import { basename, join, resolve } from 'node:path';
+import {
+  resolveGsdRoot,
+  findMilestoneIds,
+  resolveMilestoneDir,
+  resolveMilestoneFile,
+  findSliceIds,
+  resolveSliceDir,
+} from './paths.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -265,10 +272,11 @@ function parseSingleMilestone(
 
   const milestoneNodeId = `milestone:${milestoneId}`;
 
-  // Try to read the roadmap file
-  const roadmapPath = join(mDir, `${milestoneId}-ROADMAP.md`);
+  // Try to read the roadmap file. Accept both canonical M###-ROADMAP.md and
+  // legacy ROADMAP.md via the shared resolver.
+  const roadmapPath = resolveMilestoneFile(gsdRoot, milestoneId, 'ROADMAP');
   let roadmapContent: string | null = null;
-  if (existsSync(roadmapPath)) {
+  if (roadmapPath && existsSync(roadmapPath)) {
     try {
       roadmapContent = readFileSync(roadmapPath, 'utf-8');
     } catch {
@@ -290,7 +298,7 @@ function parseSingleMilestone(
       label: milestoneTitle,
       type: 'milestone',
       confidence: 'EXTRACTED',
-      sourceFile: roadmapContent ? `milestones/${milestoneId}/${milestoneId}-ROADMAP.md` : undefined,
+      sourceFile: roadmapContent ? `milestones/${milestoneId}/${basename(roadmapPath!)}` : undefined,
     });
   }
 

package/packages/mcp-server/src/readers/paths.test.ts

@@ -0,0 +1,67 @@
+// GSD MCP Server — .gsd/ path cache tests
+
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  _resetReaderCaches,
+  findMilestoneIds,
+  findSliceIds,
+  findTaskFiles,
+} from './paths.js';
+
+function makeTempDir(prefix: string): string {
+  return mkdtempSync(join(tmpdir(), `${prefix}-`));
+}
+
+function writeFixture(base: string, relPath: string, content: string): void {
+  const full = join(base, relPath);
+  mkdirSync(join(full, '..'), { recursive: true });
+  writeFileSync(full, content, 'utf8');
+}
+
+describe('reader path caches', () => {
+  beforeEach(() => {
+    _resetReaderCaches();
+  });
+
+  it('returns defensive copies of cached milestone and slice ids', () => {
+    const tmp = makeTempDir('gsd-path-cache');
+    try {
+      const gsdRoot = join(tmp, '.gsd');
+      mkdirSync(join(gsdRoot, 'milestones', 'M001', 'slices', 'S01'), { recursive: true });
+      mkdirSync(join(gsdRoot, 'milestones', 'M002'), { recursive: true });
+
+      const milestoneIds = findMilestoneIds(gsdRoot);
+      milestoneIds.push('M999');
+      assert.deepEqual(findMilestoneIds(gsdRoot), ['M001', 'M002']);
+
+      const sliceIds = findSliceIds(gsdRoot, 'M001');
+      sliceIds.push('S99');
+      assert.deepEqual(findSliceIds(gsdRoot, 'M001'), ['S01']);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it('returns defensive copies of cached task file objects', () => {
+    const tmp = makeTempDir('gsd-path-task-cache');
+    try {
+      const gsdRoot = join(tmp, '.gsd');
+      writeFixture(gsdRoot, 'milestones/M001/slices/S01/tasks/T01-PLAN.md', '# T01');
+
+      const taskFiles = findTaskFiles(gsdRoot, 'M001', 'S01');
+      taskFiles[0].hasSummary = true;
+      taskFiles.push({ id: 'T99', hasPlan: true, hasSummary: true });
+
+      assert.deepEqual(findTaskFiles(gsdRoot, 'M001', 'S01'), [
+        { id: 'T01', hasPlan: true, hasSummary: false },
+      ]);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});