gsd-pi 2.78.0 → 2.78.1-dev.2ff77b0ce

package/packages/mcp-server/dist/workflow-tools.js

@@ -1,10 +1,12 @@
 /**
  * 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";
 let workflowToolExecutorsPromise = null;
 let workflowExecutionQueue = Promise.resolve();
 let workflowWriteGatePromise = null;
@@ -113,19 +115,72 @@ function resolveActiveWorktreeBasePath(projectRoot, milestoneId) {
         return null;
     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) {
+    const worktreesDir = join(projectRoot, ".gsd", "worktrees");
+    if (!existsSync(worktreesDir))
+        return null;
+    let entries;
+    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) {
+    let resolvedHome;
+    try {
+        resolvedHome = realpathSync(resolve(homedir()));
+    }
+    catch {
+        resolvedHome = resolve(homedir());
+    }
+    let resolvedCandidate;
+    try {
+        resolvedCandidate = realpathSync(resolve(candidate));
+    }
+    catch {
+        resolvedCandidate = resolve(candidate);
+    }
+    return resolvedCandidate === resolvedHome;
+}
+export function _parseWorkflowArgsForTest(schema, args) {
+    return parseWorkflowArgs(schema, args);
+}
 function parseWorkflowArgs(schema, args) {
     const parsed = parseToolArgs(schema, args);
     // Step 1: figure out the project root. The agent shouldn't need to pass
     // 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);
-    const worktreeBasePath = resolveActiveWorktreeBasePath(projectRoot, milestoneId);
+    const worktreeBasePath = resolveActiveWorktreeBasePath(projectRoot, milestoneId)
+        ?? (milestoneId ? null : resolveSoleActiveWorktree(projectRoot));
     const effectiveBasePath = worktreeBasePath ?? projectRoot;
     return {
         ...parsed,
@@ -155,6 +210,27 @@ function isWorkflowToolExecutors(value) {
 function getSupportedSummaryArtifactTypes(executors) {
     return executors.SUPPORTED_SUMMARY_ARTIFACT_TYPES;
 }
+function buildImportCandidates(relativePath) {
+    const candidates = [];
+    const pushPreferredPair = (path) => {
+        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() {
     const candidates = [];
     const explicitModule = process.env.GSD_WORKFLOW_WRITE_GATE_MODULE?.trim();
@@ -162,37 +238,43 @@ function getWriteGateModuleCandidates() {
         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);
+    candidates.push(...buildImportCandidates("../../../src/resources/extensions/gsd/bootstrap/write-gate.js")
+        .map((p) => new URL(p, import.meta.url).href));
     return [...new Set(candidates)];
 }
 function toFileUrl(modulePath) {
     return pathToFileURL(resolve(modulePath)).href;
 }
+const warnedCustomWorkflowModuleVars = new Set();
+/**
+ * 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, value) {
+    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) {
-    // 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 = [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(relativePath) {
-    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;
     for (const candidate of candidates) {
@@ -212,9 +294,11 @@ function getWorkflowExecutorModuleCandidates(env = process.env) {
         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);
+    candidates.push(...buildImportCandidates("../../../src/resources/extensions/gsd/tools/workflow-tool-executors.js")
+        .map((p) => new URL(p, import.meta.url).href));
     return [...new Set(candidates)];
 }
 async function getWorkflowToolExecutors() {
@@ -482,6 +566,66 @@ async function ensureMilestoneDbRow(milestoneId) {
         // Ignore pre-existing rows or transient DB availability issues.
     }
 }
+async function findDatabaseMilestoneIds() {
+    try {
+        const { getAllMilestones } = await importLocalModule("../../../src/resources/extensions/gsd/gsd-db.js");
+        return (getAllMilestones?.() ?? [])
+            .map((milestone) => {
+            const id = milestone?.id;
+            return typeof id === "string" ? id : null;
+        })
+            .filter((id) => 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) {
+    const { claimReservedId, findMilestoneIds, getReservedMilestoneIds, nextMilestoneId, milestoneIdSort, } = await importLocalModule("../../../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("../../../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("../../../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) —
@@ -727,13 +871,28 @@ const sliceCompleteParams = {
 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,
     scope: z.string().describe("Scope of the decision (e.g. architecture, library, observability)"),
@@ -758,7 +917,7 @@ const requirementUpdateParams = {
 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"),
@@ -847,7 +1006,39 @@ const journalQueryParams = {
     limit: z.number().optional().describe("Maximum entries to return"),
 };
 const journalQuerySchema = z.object(journalQueryParams);
-export function registerWorkflowTools(server) {
+/**
+ * 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) {
+    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,
+                        content: [{ type: "text", text: message }],
+                    };
+                }
+            });
+        },
+    };
+}
+export function registerWorkflowTools(realServer) {
+    const server = wrapServerWithErrorHandler(realServer);
     server.tool("gsd_decision_save", "Record a project decision to the GSD database and regenerate DECISIONS.md.", decisionSaveParams, async (args) => {
         const parsed = parseWorkflowArgs(decisionSaveSchema, args);
         const { projectDir, ...params } = parsed;
@@ -859,6 +1050,7 @@ export function registerWorkflowTools(server) {
         return { content: [{ type: "text", text: `Saved decision ${result.id}` }] };
     });
     server.tool("gsd_save_decision", "Alias for gsd_decision_save. Record a project decision to the GSD database and regenerate DECISIONS.md.", decisionSaveParams, async (args) => {
+        logAliasUsage("gsd_save_decision", "gsd_decision_save");
         const parsed = parseWorkflowArgs(decisionSaveSchema, args);
         const { projectDir, ...params } = parsed;
         await enforceWorkflowWriteGate("gsd_decision_save", projectDir);
@@ -879,6 +1071,7 @@ export function registerWorkflowTools(server) {
         return { content: [{ type: "text", text: `Updated requirement ${id}` }] };
     });
     server.tool("gsd_update_requirement", "Alias for gsd_requirement_update. Update an existing requirement in the GSD database and regenerate REQUIREMENTS.md.", requirementUpdateParams, async (args) => {
+        logAliasUsage("gsd_update_requirement", "gsd_requirement_update");
         const parsed = parseWorkflowArgs(requirementUpdateSchema, args);
         const { projectDir, id, ...updates } = parsed;
         await enforceWorkflowWriteGate("gsd_requirement_update", projectDir);
@@ -899,6 +1092,7 @@ export function registerWorkflowTools(server) {
         return { content: [{ type: "text", text: `Saved requirement ${result.id}` }] };
     });
     server.tool("gsd_save_requirement", "Alias for gsd_requirement_save. Record a new requirement to the GSD database and regenerate REQUIREMENTS.md.", requirementSaveParams, async (args) => {
+        logAliasUsage("gsd_save_requirement", "gsd_requirement_save");
         const parsed = parseWorkflowArgs(requirementSaveSchema, args);
         const { projectDir, ...params } = parsed;
         await enforceWorkflowWriteGate("gsd_requirement_save", projectDir);
@@ -911,57 +1105,14 @@ export function registerWorkflowTools(server) {
     server.tool("gsd_milestone_generate_id", "Generate the next milestone ID for a new GSD milestone.", milestoneGenerateIdParams, async (args) => {
         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("../../../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("../../../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", text: id }] };
     });
     server.tool("gsd_generate_milestone_id", "Alias for gsd_milestone_generate_id. Generate the next milestone ID for a new GSD milestone.", milestoneGenerateIdParams, async (args) => {
+        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("../../../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("../../../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", text: id }] };
     });
     server.tool("gsd_plan_milestone", "Write milestone planning state to the GSD database and render ROADMAP.md from DB.", planMilestoneParams, async (args) => {
@@ -994,6 +1145,7 @@ export function registerWorkflowTools(server) {
         };
     });
     server.tool("gsd_task_plan", "Alias for gsd_plan_task. Write task planning state to the GSD database and render tasks/T##-PLAN.md from DB.", planTaskParams, async (args) => {
+        logAliasUsage("gsd_task_plan", "gsd_plan_task");
         const parsed = parseWorkflowArgs(planTaskSchema, args);
         const { projectDir, ...params } = parsed;
         await enforceWorkflowWriteGate("gsd_plan_task", projectDir, params.milestoneId);
@@ -1013,6 +1165,7 @@ export function registerWorkflowTools(server) {
         return handleReplanSlice(parsed.projectDir, parsed);
     });
     server.tool("gsd_slice_replan", "Alias for gsd_replan_slice. Replan a slice after a blocker is discovered.", replanSliceParams, async (args) => {
+        logAliasUsage("gsd_slice_replan", "gsd_replan_slice");
         const parsed = parseWorkflowArgs(replanSliceSchema, args);
         return handleReplanSlice(parsed.projectDir, parsed);
     });
@@ -1021,6 +1174,7 @@ export function registerWorkflowTools(server) {
         return handleSliceComplete(parsed.projectDir, parsed);
     });
     server.tool("gsd_complete_slice", "Alias for gsd_slice_complete. Record a completed slice to the GSD database and render summary/UAT artifacts.", sliceCompleteParams, async (args) => {
+        logAliasUsage("gsd_complete_slice", "gsd_slice_complete");
         const parsed = parseWorkflowArgs(sliceCompleteSchema, args);
         return handleSliceComplete(parsed.projectDir, parsed);
     });
@@ -1053,6 +1207,7 @@ export function registerWorkflowTools(server) {
         return handleCompleteMilestone(parsed.projectDir, parsed);
     });
     server.tool("gsd_milestone_complete", "Alias for gsd_complete_milestone. Record a completed milestone to the GSD database and render its SUMMARY.md.", completeMilestoneParams, async (args) => {
+        logAliasUsage("gsd_milestone_complete", "gsd_complete_milestone");
         const parsed = parseWorkflowArgs(completeMilestoneSchema, args);
         return handleCompleteMilestone(parsed.projectDir, parsed);
     });
@@ -1061,6 +1216,7 @@ export function registerWorkflowTools(server) {
         return handleValidateMilestone(parsed.projectDir, parsed);
     });
     server.tool("gsd_milestone_validate", "Alias for gsd_validate_milestone. Validate a milestone and render VALIDATION.md.", validateMilestoneParams, async (args) => {
+        logAliasUsage("gsd_milestone_validate", "gsd_validate_milestone");
         const parsed = parseWorkflowArgs(validateMilestoneSchema, args);
         return handleValidateMilestone(parsed.projectDir, parsed);
     });
@@ -1069,6 +1225,7 @@ export function registerWorkflowTools(server) {
         return handleReassessRoadmap(parsed.projectDir, parsed);
     });
     server.tool("gsd_roadmap_reassess", "Alias for gsd_reassess_roadmap. Reassess a roadmap after slice completion.", reassessRoadmapParams, async (args) => {
+        logAliasUsage("gsd_roadmap_reassess", "gsd_reassess_roadmap");
         const parsed = parseWorkflowArgs(reassessRoadmapSchema, args);
         return handleReassessRoadmap(parsed.projectDir, parsed);
     });
@@ -1076,10 +1233,10 @@ export function registerWorkflowTools(server) {
         const parsed = parseWorkflowArgs(saveGateResultSchema, args);
         return handleSaveGateResult(parsed.projectDir, parsed);
     });
-    server.tool("gsd_summary_save", "Save a GSD summary/research/context/assessment artifact to the database and disk.", summarySaveParams, async (args) => {
+    server.tool("gsd_summary_save", "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) => {
         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)) {
@@ -1093,6 +1250,7 @@ export function registerWorkflowTools(server) {
         return handleTaskComplete(projectDir, taskArgs);
     });
     server.tool("gsd_complete_task", "Alias for gsd_task_complete. Record a completed task to the GSD database and render its SUMMARY.md.", taskCompleteParams, async (args) => {
+        logAliasUsage("gsd_complete_task", "gsd_task_complete");
         const parsed = parseWorkflowArgs(taskCompleteSchema, args);
         const { projectDir, ...taskArgs } = parsed;
         return handleTaskComplete(projectDir, taskArgs);