gsd-pi 2.75.0 → 2.76.0

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

@@ -32,26 +32,47 @@ function resolveExternalStateRoot(allowedRoot) {
         return null;
     }
 }
-function validateProjectDir(projectDir, env = process.env) {
+export function validateProjectDir(projectDir, env = process.env) {
     if (!isAbsolute(projectDir)) {
         throw new Error(`projectDir must be an absolute path. Received: ${projectDir}`);
     }
-    const resolvedProjectDir = resolve(projectDir);
+    const lexicallyResolved = resolve(projectDir);
+    // Resolve symlinks on the candidate before the containment check so that a
+    // symlink inside the allowed root pointing outside of it cannot bypass the
+    // guard. Falls back to the lexical path if the candidate does not exist yet
+    // (legitimate for a brand-new worktree dir about to be created).
+    const resolvedProjectDir = safeRealpath(lexicallyResolved);
     const allowedRoot = getAllowedProjectRoot(env);
     if (!allowedRoot)
         return resolvedProjectDir;
-    if (isWithinRoot(resolvedProjectDir, allowedRoot))
+    const resolvedAllowedRoot = safeRealpath(allowedRoot);
+    if (isWithinRoot(resolvedProjectDir, resolvedAllowedRoot))
         return resolvedProjectDir;
     // External state layout: `<allowedRoot>/.gsd` may be a symlink into
     // `~/.gsd/projects/<hash>/`, and auto-worktrees live under
     // `~/.gsd/projects/<hash>/worktrees/<MID>/`. Accept candidates that are
     // under the realpath of `<allowedRoot>/.gsd` — they belong to this project
     // even though their absolute path is outside allowedRoot (#issue-a44).
-    const externalRoot = resolveExternalStateRoot(allowedRoot);
+    const externalRoot = resolveExternalStateRoot(resolvedAllowedRoot);
     if (externalRoot && isWithinRoot(resolvedProjectDir, externalRoot)) {
         return resolvedProjectDir;
     }
-    throw new Error(`projectDir must stay within the configured workflow project root. Received: ${resolvedProjectDir}; allowed root: ${allowedRoot}`);
+    throw new Error(`projectDir must stay within the configured workflow project root. Received: ${resolvedProjectDir}; allowed root: ${resolvedAllowedRoot}`);
+}
+function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch (err) {
+        // Only fall back for non-existent paths — a legitimate case when a worktree
+        // directory hasn't been created yet. Permission errors (EACCES), not-a-
+        // directory (ENOTDIR), etc. must propagate so we do not silently degrade
+        // to a lexical-only containment check that a restricted symlink could
+        // bypass.
+        if (err?.code === "ENOENT")
+            return path;
+        throw err;
+    }
 }
 function parseToolArgs(schema, args) {
     return schema.parse(args);
@@ -276,17 +297,55 @@ export const WORKFLOW_TOOL_NAMES = [
     "gsd_milestone_status",
     "gsd_journal_query",
 ];
+const DEFAULT_WORKFLOW_OP_TIMEOUT_MS = 5 * 60 * 1000;
+function getWorkflowOpTimeoutMs(env = process.env) {
+    const raw = env.GSD_MCP_WORKFLOW_TIMEOUT_MS?.trim();
+    if (!raw)
+        return DEFAULT_WORKFLOW_OP_TIMEOUT_MS;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return DEFAULT_WORKFLOW_OP_TIMEOUT_MS;
+    return parsed; // 0 disables the timeout
+}
 async function runSerializedWorkflowOperation(fn) {
     // The shared DB adapter and workflow log base path are process-global, so
     // workflow MCP mutations must not overlap within a single server process.
+    // A per-operation deadline prevents a single stuck call from wedging every
+    // subsequent write for the lifetime of the process.
+    //
+    // Known limitation: on timeout we surface an error and release the queue,
+    // but Promise.race cannot cancel the underlying `fn()` — it may continue
+    // running in the background and overlap with the next admitted operation.
+    // Proper cancellation requires threading an AbortSignal through every
+    // workflow executor (`workflow-tool-executors.ts` and friends), which is
+    // a larger change. The current trade-off: risk a theoretical overlap after
+    // a 5-minute wall-clock timeout vs permanently wedging the server. The
+    // overlap window is bounded by how long the zombie `fn()` keeps running;
+    // in practice DB writes complete quickly even when the caller gave up.
     const prior = workflowExecutionQueue;
     let release;
     workflowExecutionQueue = new Promise((resolve) => {
         release = resolve;
     });
     await prior;
+    const timeoutMs = getWorkflowOpTimeoutMs();
     try {
-        return await fn();
+        if (timeoutMs === 0) {
+            return await fn();
+        }
+        let timer;
+        const timeoutPromise = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                reject(new Error(`Workflow operation exceeded ${timeoutMs}ms deadline (GSD_MCP_WORKFLOW_TIMEOUT_MS)`));
+            }, timeoutMs);
+        });
+        try {
+            return await Promise.race([fn(), timeoutPromise]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
     }
     finally {
         release();
@@ -386,34 +445,75 @@ const projectDirParam = z
     .string()
     .optional()
     .describe("Optional. Omit this field — the server defaults to its current working directory, which is already the correct project or worktree root.");
+const nonEmptyString = (field) => z.string().trim().min(1, `${field} must be a non-empty string`);
+// Optional non-empty string: accepts omitted/undefined but rejects "" or
+// whitespace. Mirrors executor guards of the form
+// `value !== undefined && !isNonEmptyString(value)` — e.g. plan-task's
+// observabilityImpact. Do not preprocess "" to undefined; the executor
+// treats them differently.
+const optionalNonEmptyString = (field) => nonEmptyString(field).optional();
+// Array of non-empty strings. Mirrors executor guards that call
+// `validateStringArray` or `arr.some((item) => !isNonEmptyString(item))`.
+const nonEmptyStringArray = (field) => z.array(nonEmptyString(`${field}[]`));
+// Matches the executor's `isNonEmptyString` (trim + length>0) so Zod rejects
+// 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.
+const planMilestoneSliceSchema = z.object({
+    sliceId: nonEmptyString("sliceId"),
+    title: nonEmptyString("title"),
+    risk: nonEmptyString("risk"),
+    depends: z.array(z.string()),
+    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(),
+    // ADR-011 sketch-then-refine fields.
+    isSketch: z.boolean().optional().describe("ADR-011: true marks this slice as a sketch awaiting refine-slice expansion"),
+    sketchScope: z.string().optional().describe("ADR-011: 2-3 sentence scope boundary, required when isSketch=true"),
+}).superRefine((slice, ctx) => {
+    if (slice.isSketch === true) {
+        if (typeof slice.sketchScope !== "string" || slice.sketchScope.trim().length === 0) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["sketchScope"],
+                message: "sketchScope must be a non-empty string when isSketch is true",
+            });
+        }
+        return;
+    }
+    const required = ["successCriteria", "proofLevel", "integrationClosure", "observabilityImpact"];
+    for (const field of required) {
+        const value = slice[field];
+        if (typeof value !== "string" || value.trim().length === 0) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [field],
+                message: `${field} must be a non-empty string`,
+            });
+        }
+    }
+});
 const planMilestoneParams = {
     projectDir: projectDirParam,
-    milestoneId: z.string().describe("Milestone ID (e.g. M001)"),
-    title: z.string().describe("Milestone title"),
-    vision: z.string().describe("Milestone vision"),
-    slices: z.array(z.object({
-        sliceId: z.string(),
-        title: z.string(),
-        risk: z.string(),
-        depends: z.array(z.string()),
-        demo: z.string(),
-        goal: z.string(),
-        successCriteria: z.string(),
-        proofLevel: z.string(),
-        integrationClosure: z.string(),
-        observabilityImpact: z.string(),
-    })).describe("Planned slices for the milestone"),
+    milestoneId: nonEmptyString("milestoneId").describe("Milestone ID (e.g. M001)"),
+    title: nonEmptyString("title").describe("Milestone title"),
+    vision: nonEmptyString("vision").describe("Milestone vision"),
+    slices: z.array(planMilestoneSliceSchema).describe("Planned slices for the milestone"),
     status: z.string().optional().describe("Milestone status"),
     dependsOn: z.array(z.string()).optional().describe("Milestone dependencies"),
     successCriteria: z.array(z.string()).optional().describe("Top-level success criteria bullets"),
     keyRisks: z.array(z.object({
-        risk: z.string(),
-        whyItMatters: z.string(),
+        risk: nonEmptyString("risk"),
+        whyItMatters: nonEmptyString("whyItMatters"),
     })).optional().describe("Structured risk entries"),
     proofStrategy: z.array(z.object({
-        riskOrUnknown: z.string(),
-        retireIn: z.string(),
-        whatWillBeProven: z.string(),
+        riskOrUnknown: nonEmptyString("riskOrUnknown"),
+        retireIn: nonEmptyString("retireIn"),
+        whatWillBeProven: nonEmptyString("whatWillBeProven"),
     })).optional().describe("Structured proof strategy entries"),
     verificationContract: z.string().optional(),
     verificationIntegration: z.string().optional(),
@@ -426,19 +526,19 @@ const planMilestoneParams = {
 const planMilestoneSchema = z.object(planMilestoneParams);
 const planSliceParams = {
     projectDir: projectDirParam,
-    milestoneId: z.string().describe("Milestone ID (e.g. M001)"),
-    sliceId: z.string().describe("Slice ID (e.g. S01)"),
-    goal: z.string().describe("Slice goal"),
+    milestoneId: nonEmptyString("milestoneId").describe("Milestone ID (e.g. M001)"),
+    sliceId: nonEmptyString("sliceId").describe("Slice ID (e.g. S01)"),
+    goal: nonEmptyString("goal").describe("Slice goal"),
     tasks: z.array(z.object({
-        taskId: z.string(),
-        title: z.string(),
-        description: z.string(),
-        estimate: z.string(),
-        files: z.array(z.string()),
-        verify: z.string(),
-        inputs: z.array(z.string()),
-        expectedOutput: z.array(z.string()),
-        observabilityImpact: z.string().optional(),
+        taskId: nonEmptyString("taskId"),
+        title: nonEmptyString("title"),
+        description: nonEmptyString("description"),
+        estimate: nonEmptyString("estimate"),
+        files: nonEmptyStringArray("files"),
+        verify: nonEmptyString("verify"),
+        inputs: nonEmptyStringArray("inputs"),
+        expectedOutput: nonEmptyStringArray("expectedOutput"),
+        observabilityImpact: optionalNonEmptyString("observabilityImpact"),
     })).describe("Planned tasks for the slice"),
     successCriteria: z.string().optional(),
     proofLevel: z.string().optional(),
@@ -448,8 +548,8 @@ const planSliceParams = {
 const planSliceSchema = z.object(planSliceParams);
 const completeMilestoneParams = {
     projectDir: projectDirParam,
-    milestoneId: z.string().describe("Milestone ID (e.g. M001)"),
-    title: z.string().describe("Milestone title"),
+    milestoneId: nonEmptyString("milestoneId").describe("Milestone ID (e.g. M001)"),
+    title: nonEmptyString("title").describe("Milestone title"),
     oneLiner: z.string().describe("One-sentence summary of what the milestone achieved"),
     narrative: z.string().describe("Detailed narrative of what happened during the milestone"),
     verificationPassed: z.boolean().describe("Must be true after milestone verification succeeds"),
@@ -465,7 +565,7 @@ const completeMilestoneParams = {
 const completeMilestoneSchema = z.object(completeMilestoneParams);
 const validateMilestoneParams = {
     projectDir: projectDirParam,
-    milestoneId: z.string().describe("Milestone ID (e.g. M001)"),
+    milestoneId: nonEmptyString("milestoneId").describe("Milestone ID (e.g. M001)"),
     verdict: z.enum(["pass", "needs-attention", "needs-remediation"]).describe("Validation verdict"),
     remediationRound: z.number().describe("Remediation round (0 for first validation)"),
     successCriteriaChecklist: z.string().describe("Markdown checklist of success criteria with evidence"),
@@ -478,18 +578,18 @@ const validateMilestoneParams = {
 };
 const validateMilestoneSchema = z.object(validateMilestoneParams);
 const roadmapSliceChangeSchema = z.object({
-    sliceId: z.string(),
-    title: z.string(),
+    sliceId: nonEmptyString("sliceId"),
+    title: nonEmptyString("title"),
     risk: z.string().optional(),
     depends: z.array(z.string()).optional(),
     demo: z.string().optional(),
 });
 const reassessRoadmapParams = {
     projectDir: projectDirParam,
-    milestoneId: z.string().describe("Milestone ID (e.g. M001)"),
-    completedSliceId: z.string().describe("Slice ID that just completed"),
-    verdict: z.string().describe("Assessment verdict such as roadmap-confirmed or roadmap-adjusted"),
-    assessment: z.string().describe("Assessment text explaining the roadmap decision"),
+    milestoneId: nonEmptyString("milestoneId").describe("Milestone ID (e.g. M001)"),
+    completedSliceId: nonEmptyString("completedSliceId").describe("Slice ID that just completed"),
+    verdict: nonEmptyString("verdict").describe("Assessment verdict such as roadmap-confirmed or roadmap-adjusted"),
+    assessment: nonEmptyString("assessment").describe("Assessment text explaining the roadmap decision"),
     sliceChanges: z.object({
         modified: z.array(roadmapSliceChangeSchema),
         added: z.array(roadmapSliceChangeSchema),
@@ -501,7 +601,7 @@ const saveGateResultParams = {
     projectDir: projectDirParam,
     milestoneId: z.string().describe("Milestone ID (e.g. M001)"),
     sliceId: z.string().describe("Slice ID (e.g. S01)"),
-    gateId: z.enum(["Q3", "Q4", "Q5", "Q6", "Q7", "Q8", "MV01", "MV02", "MV03", "MV04"]).describe("Gate ID"),
+    gateId: z.string().describe("Gate ID (e.g. Q3, Q4, Q5, Q6, Q7, Q8, MV01, MV02, MV03, MV04). Accepts any string for forward-compatibility with new gates."),
     taskId: z.string().optional().describe("Task ID for task-scoped gates"),
     verdict: z.enum(["pass", "flag", "omitted"]).describe("Gate verdict"),
     rationale: z.string().describe("One-sentence justification"),
@@ -510,14 +610,14 @@ const saveGateResultParams = {
 const saveGateResultSchema = z.object(saveGateResultParams);
 const replanSliceParams = {
     projectDir: projectDirParam,
-    milestoneId: z.string().describe("Milestone ID (e.g. M001)"),
-    sliceId: z.string().describe("Slice ID (e.g. S01)"),
-    blockerTaskId: z.string().describe("Task ID that discovered the blocker"),
-    blockerDescription: z.string().describe("Description of the blocker"),
-    whatChanged: z.string().describe("Summary of what changed in the plan"),
+    milestoneId: nonEmptyString("milestoneId").describe("Milestone ID (e.g. M001)"),
+    sliceId: nonEmptyString("sliceId").describe("Slice ID (e.g. S01)"),
+    blockerTaskId: nonEmptyString("blockerTaskId").describe("Task ID that discovered the blocker"),
+    blockerDescription: nonEmptyString("blockerDescription").describe("Description of the blocker"),
+    whatChanged: nonEmptyString("whatChanged").describe("Summary of what changed in the plan"),
     updatedTasks: z.array(z.object({
-        taskId: z.string(),
-        title: z.string(),
+        taskId: nonEmptyString("taskId"),
+        title: nonEmptyString("title"),
         description: z.string(),
         estimate: z.string(),
         files: z.array(z.string()),
@@ -531,8 +631,8 @@ const replanSliceParams = {
 const replanSliceSchema = z.object(replanSliceParams);
 const sliceCompleteParams = {
     projectDir: projectDirParam,
-    sliceId: z.string().describe("Slice ID (e.g. S01)"),
-    milestoneId: z.string().describe("Milestone ID (e.g. M001)"),
+    sliceId: nonEmptyString("sliceId").describe("Slice ID (e.g. S01)"),
+    milestoneId: nonEmptyString("milestoneId").describe("Milestone ID (e.g. M001)"),
     sliceTitle: z.string().describe("Title of the slice"),
     oneLiner: z.string().describe("One-line summary of what the slice accomplished"),
     narrative: z.string().describe("Detailed narrative of what happened across all tasks"),
@@ -621,17 +721,17 @@ const milestoneGenerateIdParams = {
 const milestoneGenerateIdSchema = z.object(milestoneGenerateIdParams);
 const planTaskParams = {
     projectDir: projectDirParam,
-    milestoneId: z.string().describe("Milestone ID (e.g. M001)"),
-    sliceId: z.string().describe("Slice ID (e.g. S01)"),
-    taskId: z.string().describe("Task ID (e.g. T01)"),
-    title: z.string().describe("Task title"),
-    description: z.string().describe("Task description / steps block"),
-    estimate: z.string().describe("Task estimate"),
+    milestoneId: nonEmptyString("milestoneId").describe("Milestone ID (e.g. M001)"),
+    sliceId: nonEmptyString("sliceId").describe("Slice ID (e.g. S01)"),
+    taskId: nonEmptyString("taskId").describe("Task ID (e.g. T01)"),
+    title: nonEmptyString("title").describe("Task title"),
+    description: nonEmptyString("description").describe("Task description / steps block"),
+    estimate: nonEmptyString("estimate").describe("Task estimate"),
     files: z.array(z.string()).describe("Files likely touched"),
-    verify: z.string().describe("Verification command or block"),
+    verify: nonEmptyString("verify").describe("Verification command or block"),
     inputs: z.array(z.string()).describe("Input files or references"),
     expectedOutput: z.array(z.string()).describe("Expected output files or artifacts"),
-    observabilityImpact: z.string().optional().describe("Task observability impact"),
+    observabilityImpact: optionalNonEmptyString("observabilityImpact").describe("Task observability impact"),
 };
 const planTaskSchema = z.object(planTaskParams);
 const skipSliceParams = {
@@ -643,9 +743,9 @@ const skipSliceParams = {
 const skipSliceSchema = z.object(skipSliceParams);
 const taskCompleteParams = {
     projectDir: projectDirParam,
-    taskId: z.string().describe("Task ID (e.g. T01)"),
-    sliceId: z.string().describe("Slice ID (e.g. S01)"),
-    milestoneId: z.string().describe("Milestone ID (e.g. M001)"),
+    taskId: nonEmptyString("taskId").describe("Task ID (e.g. T01)"),
+    sliceId: nonEmptyString("sliceId").describe("Slice ID (e.g. S01)"),
+    milestoneId: nonEmptyString("milestoneId").describe("Milestone ID (e.g. M001)"),
     oneLiner: z.string().describe("One-line summary of what was accomplished"),
     narrative: z.string().describe("Detailed narrative of what happened during the task"),
     verification: z.string().describe("What was verified and how"),
@@ -654,6 +754,18 @@ const taskCompleteParams = {
     keyFiles: z.array(z.string()).optional().describe("List of key files created or modified"),
     keyDecisions: z.array(z.string()).optional().describe("List of key decisions made during this task"),
     blockerDiscovered: z.boolean().optional().describe("Whether a plan-invalidating blocker was discovered"),
+    // ADR-011 Phase 2: mid-execution escalation — agent asks the user to resolve an ambiguity.
+    escalation: z.object({
+        question: z.string().describe("The question the user needs to answer — one clear sentence."),
+        options: z.array(z.object({
+            id: z.string().describe("Short id (e.g. 'A', 'B') used by /gsd escalate resolve."),
+            label: z.string().describe("One-line label."),
+            tradeoffs: z.string().describe("1-2 sentences on the tradeoffs of this option."),
+        })).min(2).max(4).describe("2-4 options the user can choose between."),
+        recommendation: z.string().describe("Option id the executor recommends."),
+        recommendationRationale: z.string().describe("Why the recommendation — 1-2 sentences."),
+        continueWithDefault: z.boolean().describe("When true, loop continues (artifact logged for later review). When false, auto-mode pauses until the user resolves via /gsd escalate resolve."),
+    }).optional().describe("ADR-011 Phase 2: optional escalation payload. Only honored when phases.mid_execution_escalation is true."),
     verificationEvidence: z.array(z.union([
         z.object({
             command: z.string(),
@@ -753,7 +865,18 @@ export function registerWorkflowTools(server) {
                 return reserved;
             }
             const allIds = [...new Set([...findMilestoneIds(projectDir), ...getReservedMilestoneIds()])];
-            const nextId = nextMilestoneId(allIds);
+            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;
         });
@@ -770,7 +893,18 @@ export function registerWorkflowTools(server) {
                 return reserved;
             }
             const allIds = [...new Set([...findMilestoneIds(projectDir), ...getReservedMilestoneIds()])];
-            const nextId = nextMilestoneId(allIds);
+            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;
         });
@@ -910,8 +1044,10 @@ export function registerWorkflowTools(server) {
         return handleTaskComplete(projectDir, taskArgs);
     });
     server.tool("gsd_milestone_status", "Read the current status of a milestone and all its slices from the GSD database.", milestoneStatusParams, async (args) => {
+        // gsd_milestone_status is a read-only query. In-process (query-tools.ts)
+        // does not apply the write-gate; MCP must match to avoid blocking reads
+        // during pending-gate or queue-mode states.
         const { projectDir, milestoneId } = parseWorkflowArgs(milestoneStatusSchema, args);
-        await enforceWorkflowWriteGate("gsd_milestone_status", projectDir, milestoneId);
         const { executeMilestoneStatus } = await getWorkflowToolExecutors();
         return runSerializedWorkflowOperation(() => executeMilestoneStatus({ milestoneId }, projectDir));
     });