gsd-pi 2.76.0-dev.fe143342a → 2.77.0-dev.1594b263e

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

@@ -13,8 +13,10 @@
 
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
 import { z } from 'zod';
 import type { SessionManager } from './session-manager.js';
+import { isRemoteConfigured, tryRemoteQuestions } from './remote-questions.js';
 import { readProgress } from './readers/state.js';
 import { readRoadmap } from './readers/roadmap.js';
 import { readHistory } from './readers/metrics.js';
@@ -24,7 +26,7 @@ import { buildGraph, writeGraph, writeSnapshot, graphStatus, graphQuery, graphDi
 import { resolveGsdRoot } from './readers/paths.js';
 import { runDoctorLite } from './readers/doctor-lite.js';
 import { registerWorkflowTools, validateProjectDir } from './workflow-tools.js';
-import { applySecrets, checkExistingEnvKeys, detectDestination } from './env-writer.js';
+import { applySecrets, checkExistingEnvKeys, detectDestination, resolveProjectEnvFilePath } from './env-writer.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -34,6 +36,59 @@ const MCP_PKG = '@modelcontextprotocol/sdk';
 const SERVER_NAME = 'gsd';
 const SERVER_VERSION = '2.53.0';
 
+/** User-interaction timeout — generous but bounded so elicitation can't hang indefinitely (#4586). */
+const ELICIT_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
+
+/**
+ * Default child-process runner used by secure_env_collect to push secrets
+ * into `vercel env add` / `npx convex env set`. Previously `applySecrets`
+ * was called without an `execFn`, so vercel/convex destinations silently
+ * dropped every collected key. This restores the write path.
+ */
+function defaultExecFn(
+  cmd: string,
+  args: string[],
+): Promise<{ code: number; stderr: string }> {
+  return new Promise((res) => {
+    // stdin: ignore — avoids hanging if the child ever prompts interactively.
+    // stdout: ignore — consumer only cares about stderr + exit code, and an
+    //   un-drained pipe deadlocks once the kernel buffer (~64KB) fills.
+    // stderr: pipe — captured below for error surfacing.
+    const child = spawn(cmd, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString('utf8');
+    });
+    child.on('error', (err) => res({ code: 1, stderr: err.message }));
+    child.on('close', (code) => res({ code: code ?? 1, stderr }));
+  });
+}
+
+/**
+ * Race a promise against a timeout. Rejects with a typed error on timeout so
+ * callers can return a specific MCP error response rather than hanging.
+ *
+ * @param timeoutMs - override for testing; defaults to ELICIT_TIMEOUT_MS
+ */
+export async function withElicitTimeout<T>(
+  promise: Promise<T>,
+  label: string,
+  timeoutMs = ELICIT_TIMEOUT_MS,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () => reject(new Error(`${label} timed out after ${timeoutMs / 60000} minutes — no user response received`)),
+      timeoutMs,
+    );
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Tool result helpers
 // ---------------------------------------------------------------------------
@@ -332,6 +387,126 @@ export function formatAskUserQuestionsElicitResult(
   return JSON.stringify({ answers });
 }
 
+// ---------------------------------------------------------------------------
+// secure_env_collect handler (extracted so tests can drive it directly)
+// ---------------------------------------------------------------------------
+
+export type ElicitInputFn = (params: {
+  message: string;
+  requestedSchema: { type: 'object'; properties: Record<string, unknown>; required: string[] };
+}) => Promise<{ action: 'accept' | 'cancel' | 'decline'; content?: Record<string, unknown> }>;
+
+type ToolContent =
+  | { content: Array<{ type: 'text'; text: string }> }
+  | { isError: true; content: Array<{ type: 'text'; text: string }> };
+
+export async function secureEnvCollectHandler(
+  args: Record<string, unknown>,
+  elicitInput: ElicitInputFn,
+): Promise<ToolContent> {
+  const { projectDir, keys, destination, envFilePath, environment } = args as {
+    projectDir: string;
+    keys: Array<{ key: string; hint?: string; guidance?: string[] }>;
+    destination?: 'dotenv' | 'vercel' | 'convex';
+    envFilePath?: string;
+    environment?: 'development' | 'preview' | 'production';
+  };
+
+  try {
+    const resolvedProjectDir = validateProjectDir(projectDir);
+    const resolvedEnvPath = resolveProjectEnvFilePath(resolvedProjectDir, envFilePath ?? '.env');
+
+    // (1) Check which keys already exist
+    const allKeyNames = keys.map((k) => k.key);
+    const existingKeys = await checkExistingEnvKeys(allKeyNames, resolvedEnvPath);
+    const existingSet = new Set(existingKeys);
+    const pendingKeys = keys.filter((k) => !existingSet.has(k.key));
+
+    // If all keys already exist, return immediately
+    if (pendingKeys.length === 0) {
+      const lines = existingKeys.map((k) => `• ${k}: already set`);
+      return textContent(`All ${existingKeys.length} key(s) already set.\n${lines.join('\n')}`);
+    }
+
+    // (2) Build elicitation form — one string field per pending key
+    const properties: Record<string, Record<string, unknown>> = {};
+    const required: string[] = [];
+
+    for (const item of pendingKeys) {
+      const descParts: string[] = [];
+      if (item.hint) descParts.push(`Format: ${item.hint}`);
+      if (item.guidance && item.guidance.length > 0) {
+        descParts.push('How to get this:');
+        item.guidance.forEach((step, i) => descParts.push(`${i + 1}. ${step}`));
+      }
+      descParts.push('Leave empty to skip.');
+
+      properties[item.key] = {
+        type: 'string',
+        title: item.key,
+        description: descParts.join('\n'),
+      };
+      // Don't mark as required — empty string = skip
+    }
+
+    // (3) Elicit input from the MCP client
+    const elicitation = await withElicitTimeout(
+      elicitInput({
+        message: `Enter values for ${pendingKeys.length} environment variable(s). Values are written directly to the project and never shown to the AI.`,
+        requestedSchema: {
+          type: 'object',
+          properties,
+          required,
+        },
+      }),
+      'secure_env_collect',
+    );
+
+    if (elicitation.action !== 'accept' || !elicitation.content) {
+      return textContent('secure_env_collect was cancelled by user.');
+    }
+
+    // (4) Separate provided vs skipped from form response
+    const provided: Array<{ key: string; value: string }> = [];
+    const skipped: string[] = [];
+
+    for (const item of pendingKeys) {
+      const raw = elicitation.content[item.key];
+      const value = typeof raw === 'string' ? raw.trim() : '';
+      if (value.length > 0) {
+        provided.push({ key: item.key, value });
+      } else {
+        skipped.push(item.key);
+      }
+    }
+
+    // (5) Auto-detect destination if not specified
+    const resolvedDestination = destination ?? detectDestination(resolvedProjectDir);
+
+    // (6) Write secrets to destination
+    const { applied, errors } = await applySecrets(provided, resolvedDestination, {
+      envFilePath: resolvedEnvPath,
+      environment,
+      execFn: defaultExecFn,
+    });
+
+    // (7) Build result — NEVER include secret values
+    const lines: string[] = [
+      `destination: ${resolvedDestination}${!destination ? ' (auto-detected)' : ''}${environment ? ` (${environment})` : ''}`,
+    ];
+    for (const k of applied) lines.push(`✓ ${k}: applied`);
+    for (const k of skipped) lines.push(`• ${k}: skipped`);
+    for (const k of existingKeys) lines.push(`• ${k}: already set`);
+    for (const e of errors) lines.push(`✗ ${e}`);
+
+    return errors.length > 0 && applied.length === 0
+      ? errorContent(lines.join('\n'))
+      : textContent(lines.join('\n'));
+  } catch (err) {
+    return errorContent(err instanceof Error ? err.message : String(err));
+  }
+}
+
 // ---------------------------------------------------------------------------
 // createMcpServer
 // ---------------------------------------------------------------------------
@@ -342,12 +517,17 @@ export function formatAskUserQuestionsElicitResult(
  * Returns the McpServer instance — call `connect(transport)` to start serving.
  * Uses dynamic imports for the MCP SDK to avoid TS subpath resolution issues.
  */
-export async function createMcpServer(sessionManager: SessionManager): Promise<{
+export async function createMcpServer(
+  sessionManager: SessionManager,
+): Promise<{
   server: McpServerInstance;
 }> {
   // Dynamic import — same workaround as src/mcp-server.ts
   const mcpMod = await import(`${MCP_PKG}/server/mcp.js`);
-  const McpServer = mcpMod.McpServer;
+  const McpServer = mcpMod.McpServer as new (
+    info: { name: string; version: string },
+    opts: { capabilities: Record<string, unknown> },
+  ) => McpServerInstance;
 
   const server: McpServerInstance = new McpServer(
     { name: SERVER_NAME, version: SERVER_VERSION },
@@ -458,17 +638,40 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
 
   // -----------------------------------------------------------------------
   // gsd_cancel — cancel a running session
+  //
+  // Supports two lookup strategies:
+  //   1. sessionId  — the ID returned from gsd_execute (primary)
+  //   2. projectDir — absolute path to the project directory (fallback)
+  //
+  // The projectDir fallback handles interactive sessions (started via
+  // `/gsd auto` in the terminal) and post-restart MCP sessions that were
+  // never registered with a sessionId in this server instance.
   // -----------------------------------------------------------------------
   server.tool(
     'gsd_cancel',
-    'Cancel a running GSD session. Aborts the current operation and stops the process.',
+    'Cancel a running GSD session. Aborts the current operation and stops the process. Provide sessionId (from gsd_execute) or projectDir as a fallback for interactive/restarted sessions.',
     {
-      sessionId: z.string().describe('Session ID returned from gsd_execute'),
+      sessionId: z.string().optional().describe('Session ID returned from gsd_execute'),
+      projectDir: z.string().optional().describe('Absolute path to the project directory (fallback when sessionId is unavailable)'),
     },
     async (args: Record<string, unknown>) => {
-      const { sessionId } = args as { sessionId: string };
+      const { sessionId, projectDir } = args as { sessionId?: string; projectDir?: string };
       try {
-        await sessionManager.cancelSession(sessionId);
+        if (!sessionId && !projectDir) {
+          return errorContent('Either sessionId or projectDir must be provided');
+        }
+        if (sessionId) {
+          try {
+            await sessionManager.cancelSession(sessionId);
+          } catch (err) {
+            if (!projectDir || !(err instanceof Error) || !err.message.includes('Session not found')) {
+              throw err;
+            }
+            await sessionManager.cancelSessionByDir(projectDir);
+          }
+        } else if (projectDir) {
+          await sessionManager.cancelSessionByDir(projectDir);
+        }
         return jsonContent({ cancelled: true });
       } catch (err) {
         return errorContent(err instanceof Error ? err.message : String(err));
@@ -545,13 +748,33 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
         allowMultiple: z.boolean().optional().describe('If true, the user can select multiple options. No "None of the above" option is added.'),
       })).describe('Questions to show the user. Prefer 1 and do not exceed 3.'),
     },
-    async (args: Record<string, unknown>) => {
+    async (args: Record<string, unknown>, extra?: McpToolExtra) => {
       const { questions } = args as unknown as AskUserQuestionsParams;
       try {
         const validationError = validateAskUserQuestionsPayload(questions);
         if (validationError) return errorContent(validationError);
 
-        const elicitation = await server.server.elicitInput(buildAskUserQuestionsElicitRequest(questions));
+        // Delegate to remote-questions manager when a remote channel is configured
+        // (Discord, Slack, Telegram). This path is the only one reachable for
+        // Claude Code-under-gsd sessions, which have no local TUI.
+        if (isRemoteConfigured()) {
+          const remoteResult = await tryRemoteQuestions(questions, extra?.signal);
+          if (remoteResult) {
+            const details = remoteResult.details as Record<string, unknown> | undefined;
+            if (details?.['timed_out'] || details?.['error']) {
+              // Surface timeout/error as plain text so the LLM knows to retry
+              return textContent(remoteResult.content[0]?.text ?? 'Remote questions timed out or failed');
+            }
+            return textContent(remoteResult.content[0]?.text ?? '');
+          }
+          // resolveRemoteConfig() returned null between isRemoteConfigured() and
+          // tryRemoteQuestions() (e.g. env var was cleared) — fall through to local.
+        }
+
+        const elicitation = await withElicitTimeout(
+          server.server.elicitInput(buildAskUserQuestionsElicitRequest(questions)),
+          'ask_user_questions',
+        );
         if (elicitation.action !== 'accept' || !elicitation.content) {
           return textContent('ask_user_questions was cancelled before receiving a response');
         }
@@ -580,105 +803,10 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
       envFilePath: z.string().optional().describe('Path to .env file (dotenv only). Defaults to .env in projectDir.'),
       environment: z.enum(['development', 'preview', 'production']).optional().describe('Target environment (vercel/convex only)'),
     },
-    async (args: Record<string, unknown>) => {
-      const { projectDir, keys, destination, envFilePath, environment } = args as {
-        projectDir: string;
-        keys: Array<{ key: string; hint?: string; guidance?: string[] }>;
-        destination?: 'dotenv' | 'vercel' | 'convex';
-        envFilePath?: string;
-        environment?: 'development' | 'preview' | 'production';
-      };
-
-      try {
-        const resolvedProjectDir = validateProjectDir(projectDir);
-        const resolvedEnvPath = resolve(resolvedProjectDir, envFilePath ?? '.env');
-
-        // (1) Check which keys already exist
-        const allKeyNames = keys.map((k) => k.key);
-        const existingKeys = await checkExistingEnvKeys(allKeyNames, resolvedEnvPath);
-        const existingSet = new Set(existingKeys);
-        const pendingKeys = keys.filter((k) => !existingSet.has(k.key));
-
-        // If all keys already exist, return immediately
-        if (pendingKeys.length === 0) {
-          const lines = existingKeys.map((k) => `• ${k}: already set`);
-          return textContent(`All ${existingKeys.length} key(s) already set.\n${lines.join('\n')}`);
-        }
-
-        // (2) Build elicitation form — one string field per pending key
-        const properties: Record<string, Record<string, unknown>> = {};
-        const required: string[] = [];
-
-        for (const item of pendingKeys) {
-          const descParts: string[] = [];
-          if (item.hint) descParts.push(`Format: ${item.hint}`);
-          if (item.guidance && item.guidance.length > 0) {
-            descParts.push('How to get this:');
-            item.guidance.forEach((step, i) => descParts.push(`${i + 1}. ${step}`));
-          }
-          descParts.push('Leave empty to skip.');
-
-          properties[item.key] = {
-            type: 'string',
-            title: item.key,
-            description: descParts.join('\n'),
-          };
-          // Don't mark as required — empty string = skip
-        }
-
-        // (3) Elicit input from the MCP client
-        const elicitation = await server.server.elicitInput({
-          message: `Enter values for ${pendingKeys.length} environment variable(s). Values are written directly to the project and never shown to the AI.`,
-          requestedSchema: {
-            type: 'object',
-            properties,
-            required,
-          },
-        });
-
-        if (elicitation.action !== 'accept' || !elicitation.content) {
-          return textContent('secure_env_collect was cancelled by user.');
-        }
-
-        // (4) Separate provided vs skipped from form response
-        const provided: Array<{ key: string; value: string }> = [];
-        const skipped: string[] = [];
-
-        for (const item of pendingKeys) {
-          const raw = elicitation.content[item.key];
-          const value = typeof raw === 'string' ? raw.trim() : '';
-          if (value.length > 0) {
-            provided.push({ key: item.key, value });
-          } else {
-            skipped.push(item.key);
-          }
-        }
-
-        // (5) Auto-detect destination if not specified
-        const resolvedDestination = destination ?? detectDestination(resolvedProjectDir);
-
-        // (6) Write secrets to destination
-        const { applied, errors } = await applySecrets(provided, resolvedDestination, {
-          envFilePath: resolvedEnvPath,
-          environment,
-        });
-
-        // (7) Build result — NEVER include secret values
-        const lines: string[] = [
-          `destination: ${resolvedDestination}${!destination ? ' (auto-detected)' : ''}${environment ? ` (${environment})` : ''}`,
-        ];
-        for (const k of applied) lines.push(`✓ ${k}: applied`);
-        for (const k of skipped) lines.push(`• ${k}: skipped`);
-        for (const k of existingKeys) lines.push(`• ${k}: already set`);
-        for (const e of errors) lines.push(`✗ ${e}`);
-
-        return errors.length > 0 && applied.length === 0
-          ? errorContent(lines.join('\n'))
-          : textContent(lines.join('\n'));
-      } catch (err) {
-        return errorContent(err instanceof Error ? err.message : String(err));
-      }
-    },
+    async (args: Record<string, unknown>) =>
+      secureEnvCollectHandler(args, (params) =>
+        server.server.elicitInput(params as ElicitRequestFormParams),
+      ),
   );
 
   // =======================================================================

package/packages/mcp-server/src/session-manager.ts

@@ -7,7 +7,8 @@
  */
 
 import { execSync } from 'node:child_process';
-import { resolve } from 'node:path';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
 import { RpcClient } from '@gsd-build/rpc-client';
 import type { SdkAgentEvent, RpcInitResult, RpcCostUpdateEvent, RpcExtensionUIRequest } from '@gsd-build/rpc-client';
 import type {
@@ -188,7 +189,48 @@ export class SessionManager {
   async cancelSession(sessionId: string): Promise<void> {
     const session = this.getSession(sessionId);
     if (!session) throw new Error(`Session not found: ${sessionId}`);
+    await this._cancelSessionObject(session);
+  }
+
+  /**
+   * Cancel a session looked up by project directory.
+   *
+   * This is the fallback path for interactive sessions (started via `/gsd auto`
+   * in the terminal) and sessions from a restarted MCP server that have no
+   * registered sessionId. The sessions map is keyed by projectDir, so this
+   * lookup always succeeds for any tracked session regardless of sessionId.
+   */
+  async cancelSessionByDir(projectDir: string): Promise<void> {
+    const session = this.getSessionByDir(projectDir);
+    if (session) {
+      await this._cancelSessionObject(session);
+      return;
+    }
+    const stopped = await this.stopDetachedAutoProcess(projectDir);
+    if (!stopped) {
+      throw new Error(`Session not found for projectDir: ${projectDir}`);
+    }
+  }
+
+  private async stopDetachedAutoProcess(projectDir: string): Promise<boolean> {
+    const lockPath = join(projectDir, '.gsd', 'auto.lock');
+    if (!existsSync(lockPath)) return false;
+    try {
+      const lockData = JSON.parse(readFileSync(lockPath, 'utf-8')) as { pid?: number };
+      const pid = lockData.pid;
+      if (typeof pid !== 'number') return false;
+      try { process.kill(pid, 0); } catch { return false; }
+      process.kill(pid, 'SIGTERM');
+      return true;
+    } catch {
+      return false;
+    }
+  }
 
+  /**
+   * Internal: perform abort + stop + mark cancelled on a resolved session object.
+   */
+  private async _cancelSessionObject(session: ManagedSession): Promise<void> {
     try {
       await session.client.abort();
     } catch { /* may already be stopped */ }

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

@@ -712,6 +712,91 @@ export const executeTaskComplete = async (params, projectDir) => {
     }
   });
 
+  it("gsd_plan_milestone rejects a full slice with missing heavy fields via a behavioral round-trip", async () => {
+    // Behavioral guard for the full-vs-sketch conditional. The original
+    // regression (invisible "required unless isSketch" requirement) is
+    // surfaced to users through two distinct runtime channels:
+    //   1. A parse-time rejection when the tool is called with empty heavy
+    //      fields on a non-sketch slice (no isSketch=true).
+    //   2. An acceptance when isSketch=true + sketchScope is supplied and
+    //      heavy fields are omitted.
+    // Both arms are exercised below against the live handler — any schema
+    // refactor that preserves the user-observable contract (rejection +
+    // acceptance) passes, and any refactor that breaks the contract
+    // fails, regardless of whether internal `.describe()` prose changes.
+    const base = makeTmpBase();
+    try {
+      const server = makeMockServer();
+      registerWorkflowTools(server as any);
+      const milestoneTool = server.tools.find((t) => t.name === "gsd_plan_milestone");
+      assert.ok(milestoneTool, "milestone planning tool should be registered");
+
+      // Arm 1: full slice (isSketch omitted) with the heavy fields missing
+      // must reject and name ALL four fields so the agent can self-correct.
+      let fullError: unknown;
+      try {
+        await milestoneTool!.handler({
+          projectDir: base,
+          milestoneId: "M001",
+          title: "Full slice path",
+          vision: "Behavioral test for isSketch conditional.",
+          slices: [
+            {
+              sliceId: "S01",
+              title: "Heavy slice",
+              risk: "medium",
+              depends: [],
+              demo: "Demo.",
+              goal: "Goal.",
+              // heavy fields intentionally omitted
+            },
+          ],
+        });
+      } catch (err) {
+        fullError = err;
+      }
+      assert.ok(fullError, "a non-sketch slice without heavy fields must reject");
+      const fullMsg = fullError instanceof Error ? fullError.message : String(fullError);
+      for (const field of ["successCriteria", "proofLevel", "integrationClosure", "observabilityImpact"]) {
+        assert.ok(
+          fullMsg.includes(field),
+          `rejection must name ${field} so agents can recover without a second round-trip; got: ${fullMsg}`,
+        );
+      }
+
+      // Arm 2: sketch slice (isSketch=true + sketchScope) with heavy fields
+      // omitted must be accepted — proving the conditional is live. Assert
+      // success directly rather than just checking a thrown message omits
+      // the heavy-field names: a generic failure would otherwise silently
+      // pass this arm.
+      const sketchResult = await milestoneTool!.handler({
+        projectDir: base,
+        milestoneId: "M002",
+        title: "Sketch slice path",
+        vision: "Behavioral test for isSketch conditional.",
+        slices: [
+          {
+            sliceId: "S01",
+            title: "Sketch slice",
+            risk: "medium",
+            depends: [],
+            demo: "Demo.",
+            goal: "Goal.",
+            isSketch: true,
+            sketchScope: "Two-sentence scope. Boundary defined.",
+          },
+        ],
+      });
+      assert.match(
+        (sketchResult as any).content[0].text as string,
+        /Planned milestone M002/,
+        "sketch slice with isSketch=true must be accepted by the handler",
+      );
+    } finally {
+      cleanup(base);
+    }
+  });
+
   it("gsd_plan_milestone requires sketchScope when isSketch=true and skips heavy fields", async () => {
     const base = makeTmpBase();
     try {

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

@@ -875,6 +875,17 @@ const nonEmptyStringArray = (field: string) =>
 // empty/whitespace fields at parse time. Without this, MCP callers pass "" for
 // the heavy planning fields, Zod accepts it, and the executor rejects one
 // field per call — forcing the agent into a retry loop to discover every gap.
+//
+// #4759 follow-up: the four heavy fields are Zod-optional because sketch
+// slices (isSketch=true) legitimately omit them, but they are REQUIRED for
+// every other slice. The conditional requirement is invisible in the JSON
+// Schema `required` array, so callers can only discover it from the
+// descriptions or by hitting the runtime superRefine below. The `.describe()`
+// calls below make that contract unmistakable in the tool schema sent to
+// agents; the superRefine enforces it at parse time.
+const HEAVY_FIELD_DESCRIBE = (field: string) =>
+  `${field} for this slice. REQUIRED unless isSketch=true (sketch slices defer this to refine-slice).`;
+
 const planMilestoneSliceSchema = z.object({
   sliceId: nonEmptyString("sliceId"),
   title: nonEmptyString("title"),
@@ -883,14 +894,16 @@ const planMilestoneSliceSchema = z.object({
   demo: nonEmptyString("demo"),
   goal: nonEmptyString("goal"),
   // ADR-011: heavy planning fields are optional for sketch slices; required for full slices.
-  successCriteria: z.string().optional(),
-  proofLevel: z.string().optional(),
-  integrationClosure: z.string().optional(),
-  observabilityImpact: z.string().optional(),
+  successCriteria: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("successCriteria")),
+  proofLevel: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("proofLevel")),
+  integrationClosure: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("integrationClosure")),
+  observabilityImpact: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("observabilityImpact")),
   // ADR-011 sketch-then-refine fields.
-  isSketch: z.boolean().optional().describe("ADR-011: true marks this slice as a sketch awaiting refine-slice expansion"),
+  isSketch: z.boolean().optional().describe("ADR-011: true marks this slice as a sketch awaiting refine-slice expansion. When true, successCriteria/proofLevel/integrationClosure/observabilityImpact may be omitted and sketchScope becomes required."),
   sketchScope: z.string().optional().describe("ADR-011: 2-3 sentence scope boundary, required when isSketch=true"),
-}).superRefine((slice, ctx) => {
+}).describe(
+  "Planned slice. For full slices (isSketch omitted or false): successCriteria, proofLevel, integrationClosure, and observabilityImpact are all required. For sketch slices (isSketch=true): those four fields may be omitted, but sketchScope is required.",
+).superRefine((slice, ctx) => {
   if (slice.isSketch === true) {
     if (typeof slice.sketchScope !== "string" || slice.sketchScope.trim().length === 0) {
       ctx.addIssue({

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

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