gsd-pi 2.78.0 → 2.78.1-dev.2ff77b0ce

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

@@ -2,11 +2,14 @@
  * Workflow MCP tools — exposes the core GSD mutation/read handlers over MCP.
  */
 
-import { existsSync, realpathSync } from "node:fs";
+import { existsSync, readdirSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { z } from "zod";
 
+import { logAliasUsage } from "./alias-telemetry.js";
+
 type WorkflowToolExecutors = {
   SUPPORTED_SUMMARY_ARTIFACT_TYPES: readonly string[];
   executeMilestoneStatus: (params: { milestoneId: string }, basePath?: string) => Promise<unknown>;
@@ -190,7 +193,7 @@ type WorkflowToolExecutors = {
   ) => Promise<unknown>;
   executeSummarySave: (
     params: {
-      milestone_id: string;
+      milestone_id?: string;
       slice_id?: string;
       task_id?: string;
       artifact_type: string;
@@ -376,6 +379,50 @@ function resolveActiveWorktreeBasePath(
   return wtPath;
 }
 
+/**
+ * Fallback when the tool call has no milestoneId: if exactly one auto-worktree
+ * exists under `<projectRoot>/.gsd/worktrees/`, treat it as the active one.
+ * Multiple worktrees → ambiguous, return null and let writes go to project root.
+ */
+function resolveSoleActiveWorktree(projectRoot: string): string | null {
+  const worktreesDir = join(projectRoot, ".gsd", "worktrees");
+  if (!existsSync(worktreesDir)) return null;
+  let entries: string[];
+  try {
+    entries = readdirSync(worktreesDir);
+  } catch {
+    return null;
+  }
+  const live = entries
+    .map((name) => join(worktreesDir, name))
+    .filter((p) => existsSync(join(p, ".git")));
+  if (live.length !== 1) return null;
+  return live[0];
+}
+
+function isHomeDirectory(candidate: string): boolean {
+  let resolvedHome: string;
+  try {
+    resolvedHome = realpathSync(resolve(homedir()));
+  } catch {
+    resolvedHome = resolve(homedir());
+  }
+  let resolvedCandidate: string;
+  try {
+    resolvedCandidate = realpathSync(resolve(candidate));
+  } catch {
+    resolvedCandidate = resolve(candidate);
+  }
+  return resolvedCandidate === resolvedHome;
+}
+
+export function _parseWorkflowArgsForTest<T extends { projectDir?: string }>(
+  schema: z.ZodType<T>,
+  args: Record<string, unknown>,
+): T & { projectDir: string } {
+  return parseWorkflowArgs(schema, args);
+}
+
 function parseWorkflowArgs<T extends { projectDir?: string }>(
   schema: z.ZodType<T>,
   args: Record<string, unknown>,
@@ -385,14 +432,28 @@ function parseWorkflowArgs<T extends { projectDir?: string }>(
   // projectDir — default to process.cwd() which the MCP server inherited from
   // Claude Code (launched at the project root).
   const projectRootCandidate = parsed.projectDir ?? process.cwd();
+
+  // Defense-in-depth: refuse when the resolved candidate is the user's home
+  // directory. The MCP server's process.cwd() can be $HOME if launched from
+  // an unusual context; honoring it would write project artifacts into ~/.gsd.
+  if (isHomeDirectory(projectRootCandidate)) {
+    throw new Error(
+      `projectDir resolves to the user's home directory (${projectRootCandidate}). ` +
+      `Run the workflow tool from inside a project directory, or pass an explicit projectDir.`,
+    );
+  }
+
   const projectRoot = validateProjectDir(projectRootCandidate);
 
   // Step 2: if this tool call is scoped to a milestone that has an active
   // auto-worktree, re-route writes to the worktree's .gsd rather than the
   // project's shared .gsd. auto-mode's verifyExpectedArtifact runs against
   // the worktree, and a mismatch here causes every unit to retry once.
+  // When the agent omits milestoneId, fall back to the sole live worktree
+  // if exactly one exists — that's the active auto-mode session.
   const milestoneId = extractMilestoneId(parsed as Record<string, unknown>);
-  const worktreeBasePath = resolveActiveWorktreeBasePath(projectRoot, milestoneId);
+  const worktreeBasePath = resolveActiveWorktreeBasePath(projectRoot, milestoneId)
+    ?? (milestoneId ? null : resolveSoleActiveWorktree(projectRoot));
   const effectiveBasePath = worktreeBasePath ?? projectRoot;
 
   return {
@@ -426,6 +487,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();
@@ -433,13 +517,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)];
@@ -449,28 +533,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;
@@ -491,13 +584,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)];
@@ -847,6 +940,80 @@ async function ensureMilestoneDbRow(milestoneId: string): Promise<void> {
   }
 }
 
+async function findDatabaseMilestoneIds(): Promise<string[]> {
+  try {
+    const { getAllMilestones } = await importLocalModule<any>("../../../src/resources/extensions/gsd/gsd-db.js");
+    return (getAllMilestones?.() ?? [])
+      .map((milestone: unknown) => {
+        const id = (milestone as { id?: unknown })?.id;
+        return typeof id === "string" ? id : null;
+      })
+      .filter((id: string | null): id is string => id !== null);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Fix #4996: Shared helper for both gsd_milestone_generate_id and
+ * gsd_generate_milestone_id. Reuses the lowest reusable ghost milestone ID
+ * (a disk-only stub with no DB row, no worktree, no content files) before
+ * falling back to max+1. Uses the stricter `isReusableGhostMilestone` —
+ * not `isGhostMilestone` — to avoid racing with in-flight queued DB rows
+ * from an earlier call to this same tool.
+ */
+async function generateOrReuseMilestoneId(projectDir: string): Promise<string> {
+  const {
+    claimReservedId,
+    findMilestoneIds,
+    getReservedMilestoneIds,
+    nextMilestoneId,
+    milestoneIdSort,
+  } = await importLocalModule<any>("../../../src/resources/extensions/gsd/milestone-ids.js");
+
+  const reserved = claimReservedId();
+  if (reserved) {
+    await ensureMilestoneDbRow(reserved);
+    return reserved;
+  }
+
+  const allIds = [
+    ...new Set([
+      ...findMilestoneIds(projectDir),
+      ...getReservedMilestoneIds(),
+      ...(await findDatabaseMilestoneIds()),
+    ]),
+  ];
+
+  // Attempt ghost-ID reuse before falling back to max+1.
+  const { isReusableGhostMilestone } = await importLocalModule<any>(
+    "../../../src/resources/extensions/gsd/state.js",
+  );
+  const sorted = [...allIds].sort(milestoneIdSort);
+  for (const candidate of sorted) {
+    if (isReusableGhostMilestone(projectDir, candidate)) {
+      await ensureMilestoneDbRow(candidate);
+      return candidate;
+    }
+  }
+
+  const prefsMod = await importLocalModule<any>(
+    "../../../src/resources/extensions/gsd/preferences.js",
+  ).catch(() => null);
+  // Graceful degradation: a corrupt preferences file should not crash
+  // milestone-id generation. Fall back to non-unique IDs if anything
+  // throws here — matches the pre-fix behavior for missing prefs.
+  let uniqueEnabled = false;
+  try {
+    uniqueEnabled = !!prefsMod?.loadEffectiveGSDPreferences?.(projectDir)?.preferences?.unique_milestone_ids;
+  } catch {
+    uniqueEnabled = false;
+  }
+  const nextId = nextMilestoneId(allIds, uniqueEnabled);
+  await ensureMilestoneDbRow(nextId);
+  return nextId;
+}
+
 // projectDir is optional. When omitted, the server uses process.cwd(). This
 // prevents the agent from burning tokens reasoning about which absolute path
 // to pass (git root vs worktree vs symlink-resolved external state layout) —
@@ -1112,13 +1279,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,
@@ -1146,7 +1328,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"),
@@ -1244,7 +1426,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.",
@@ -1266,6 +1480,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_decision_save. Record a project decision to the GSD database and regenerate DECISIONS.md.",
     decisionSaveParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_save_decision", "gsd_decision_save");
       const parsed = parseWorkflowArgs(decisionSaveSchema, args);
       const { projectDir, ...params } = parsed;
       await enforceWorkflowWriteGate("gsd_decision_save", projectDir);
@@ -1298,6 +1513,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_requirement_update. Update an existing requirement in the GSD database and regenerate REQUIREMENTS.md.",
     requirementUpdateParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_update_requirement", "gsd_requirement_update");
       const parsed = parseWorkflowArgs(requirementUpdateSchema, args);
       const { projectDir, id, ...updates } = parsed;
       await enforceWorkflowWriteGate("gsd_requirement_update", projectDir);
@@ -1330,6 +1546,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_requirement_save. Record a new requirement to the GSD database and regenerate REQUIREMENTS.md.",
     requirementSaveParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_save_requirement", "gsd_requirement_save");
       const parsed = parseWorkflowArgs(requirementSaveSchema, args);
       const { projectDir, ...params } = parsed;
       await enforceWorkflowWriteGate("gsd_requirement_save", projectDir);
@@ -1348,35 +1565,9 @@ export function registerWorkflowTools(server: McpToolServer): void {
     async (args: Record<string, unknown>) => {
       const { projectDir } = parseWorkflowArgs(milestoneGenerateIdSchema, args);
       await enforceWorkflowWriteGate("gsd_milestone_generate_id", projectDir);
-      const id = await runSerializedWorkflowDbOperation(projectDir, async () => {
-        const {
-          claimReservedId,
-          findMilestoneIds,
-          getReservedMilestoneIds,
-          nextMilestoneId,
-        } = await importLocalModule<any>("../../../src/resources/extensions/gsd/milestone-ids.js");
-        const reserved = claimReservedId();
-        if (reserved) {
-          await ensureMilestoneDbRow(reserved);
-          return reserved;
-        }
-        const allIds = [...new Set([...findMilestoneIds(projectDir), ...getReservedMilestoneIds()])];
-        const prefsMod = await importLocalModule<any>(
-          "../../../src/resources/extensions/gsd/preferences.js",
-        ).catch(() => null);
-        // Graceful degradation: a corrupt preferences file should not crash
-        // milestone-id generation. Fall back to non-unique IDs if anything
-        // throws here — matches the pre-fix behavior for missing prefs.
-        let uniqueEnabled = false;
-        try {
-          uniqueEnabled = !!prefsMod?.loadEffectiveGSDPreferences?.()?.preferences?.unique_milestone_ids;
-        } catch {
-          uniqueEnabled = false;
-        }
-        const nextId = nextMilestoneId(allIds, uniqueEnabled);
-        await ensureMilestoneDbRow(nextId);
-        return nextId;
-      });
+      const id = await runSerializedWorkflowDbOperation(projectDir, () =>
+        generateOrReuseMilestoneId(projectDir),
+      );
       return { content: [{ type: "text" as const, text: id }] };
     },
   );
@@ -1386,37 +1577,12 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_milestone_generate_id. Generate the next milestone ID for a new GSD milestone.",
     milestoneGenerateIdParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_generate_milestone_id", "gsd_milestone_generate_id");
       const { projectDir } = parseWorkflowArgs(milestoneGenerateIdSchema, args);
       await enforceWorkflowWriteGate("gsd_milestone_generate_id", projectDir);
-      const id = await runSerializedWorkflowDbOperation(projectDir, async () => {
-        const {
-          claimReservedId,
-          findMilestoneIds,
-          getReservedMilestoneIds,
-          nextMilestoneId,
-        } = await importLocalModule<any>("../../../src/resources/extensions/gsd/milestone-ids.js");
-        const reserved = claimReservedId();
-        if (reserved) {
-          await ensureMilestoneDbRow(reserved);
-          return reserved;
-        }
-        const allIds = [...new Set([...findMilestoneIds(projectDir), ...getReservedMilestoneIds()])];
-        const prefsMod = await importLocalModule<any>(
-          "../../../src/resources/extensions/gsd/preferences.js",
-        ).catch(() => null);
-        // Graceful degradation: a corrupt preferences file should not crash
-        // milestone-id generation. Fall back to non-unique IDs if anything
-        // throws here — matches the pre-fix behavior for missing prefs.
-        let uniqueEnabled = false;
-        try {
-          uniqueEnabled = !!prefsMod?.loadEffectiveGSDPreferences?.()?.preferences?.unique_milestone_ids;
-        } catch {
-          uniqueEnabled = false;
-        }
-        const nextId = nextMilestoneId(allIds, uniqueEnabled);
-        await ensureMilestoneDbRow(nextId);
-        return nextId;
-      });
+      const id = await runSerializedWorkflowDbOperation(projectDir, () =>
+        generateOrReuseMilestoneId(projectDir),
+      );
       return { content: [{ type: "text" as const, text: id }] };
     },
   );
@@ -1477,6 +1643,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_plan_task. Write task planning state to the GSD database and render tasks/T##-PLAN.md from DB.",
     planTaskParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_task_plan", "gsd_plan_task");
       const parsed = parseWorkflowArgs(planTaskSchema, args);
       const { projectDir, ...params } = parsed;
       await enforceWorkflowWriteGate("gsd_plan_task", projectDir, params.milestoneId);
@@ -1508,6 +1675,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_replan_slice. Replan a slice after a blocker is discovered.",
     replanSliceParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_slice_replan", "gsd_replan_slice");
       const parsed = parseWorkflowArgs(replanSliceSchema, args);
       return handleReplanSlice(parsed.projectDir, parsed);
     },
@@ -1528,6 +1696,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_slice_complete. Record a completed slice to the GSD database and render summary/UAT artifacts.",
     sliceCompleteParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_complete_slice", "gsd_slice_complete");
       const parsed = parseWorkflowArgs(sliceCompleteSchema, args);
       return handleSliceComplete(parsed.projectDir, parsed);
     },
@@ -1578,6 +1747,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_complete_milestone. Record a completed milestone to the GSD database and render its SUMMARY.md.",
     completeMilestoneParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_milestone_complete", "gsd_complete_milestone");
       const parsed = parseWorkflowArgs(completeMilestoneSchema, args);
       return handleCompleteMilestone(parsed.projectDir, parsed);
     },
@@ -1598,6 +1768,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_validate_milestone. Validate a milestone and render VALIDATION.md.",
     validateMilestoneParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_milestone_validate", "gsd_validate_milestone");
       const parsed = parseWorkflowArgs(validateMilestoneSchema, args);
       return handleValidateMilestone(parsed.projectDir, parsed);
     },
@@ -1618,6 +1789,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_reassess_roadmap. Reassess a roadmap after slice completion.",
     reassessRoadmapParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_roadmap_reassess", "gsd_reassess_roadmap");
       const parsed = parseWorkflowArgs(reassessRoadmapSchema, args);
       return handleReassessRoadmap(parsed.projectDir, parsed);
     },
@@ -1635,12 +1807,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)) {
@@ -1672,6 +1844,7 @@ export function registerWorkflowTools(server: McpToolServer): void {
     "Alias for gsd_task_complete. Record a completed task to the GSD database and render its SUMMARY.md.",
     taskCompleteParams,
     async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_complete_task", "gsd_task_complete");
       const parsed = parseWorkflowArgs(taskCompleteSchema, args);
       const { projectDir, ...taskArgs } = parsed;
       return handleTaskComplete(projectDir, taskArgs);