gsd-pi 2.79.0-dev.ece5fd8ba → 2.80.0-dev.c5f2443b3

package/packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd-build/mcp-server",
-  "version": "2.79.0",
+  "version": "2.80.0",
   "description": "MCP server exposing GSD orchestration tools for Claude Code, Cursor, and other MCP clients",
   "license": "MIT",
   "gsd": {
@@ -34,8 +34,9 @@
     "test": "npm run build:test && node --test dist/mcp-server.test.js dist/remote-questions.test.js"
   },
   "dependencies": {
+    "@gsd-build/contracts": "^2.80.0",
+    "@gsd-build/rpc-client": "^2.80.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@gsd-build/rpc-client": "^2.79.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {

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

@@ -882,6 +882,144 @@ describe('createMcpServer tool registration', () => {
     );
   });
 
+  it('ask_user_questions persists confirmed depth gates for local answers', async () => {
+    const questions = [
+      {
+        id: 'depth_verification_M003_confirm',
+        header: 'Depth Check',
+        question: 'Did I capture the depth right?',
+        options: [
+          { label: 'Yes, you got it (Recommended)', description: 'Continue with the current summary.' },
+          { label: 'Not quite', description: 'I need to clarify the depth further.' },
+        ],
+      },
+    ];
+    const calls: string[] = [];
+    const writeGate = {
+      isGateQuestionId(questionId: string) {
+        return questionId.startsWith('depth_verification_');
+      },
+      isDepthConfirmationAnswer(selected: unknown, options?: Array<{ label?: string }>) {
+        return selected === options?.[0]?.label;
+      },
+      setPendingGate(gateId: string, basePath: string) {
+        calls.push(`pending:${gateId}:${basePath}`);
+      },
+      markApprovalGateVerified(gateId?: string | null, basePath?: string) {
+        calls.push(`approval:${gateId}:${basePath}`);
+      },
+      markDepthVerified(milestoneId?: string | null, basePath?: string) {
+        calls.push(`depth:${milestoneId}:${basePath}`);
+      },
+      clearPendingGate(basePath: string) {
+        calls.push(`clear:${basePath}`);
+      },
+      extractDepthVerificationMilestoneId(questionId: string) {
+        return questionId.match(/_(M\d+)_/)?.[1] ?? null;
+      },
+    };
+
+    const result = await askUserQuestionsHandler(questions, undefined, {
+      async elicitInput() {
+        return {
+          action: 'accept',
+          content: {
+            depth_verification_M003_confirm: 'Yes, you got it (Recommended)',
+          },
+        };
+      },
+      isRemoteConfigured() {
+        return false;
+      },
+      async tryRemoteQuestions() {
+        throw new Error('should not be called');
+      },
+      writeGate,
+      writeGateBasePath: '/tmp/gsd-project',
+    });
+
+    assert.equal('isError' in result && result.isError, false);
+    assert.deepEqual(calls, [
+      'pending:depth_verification_M003_confirm:/tmp/gsd-project',
+      'approval:depth_verification_M003_confirm:/tmp/gsd-project',
+      'depth:M003:/tmp/gsd-project',
+      'clear:/tmp/gsd-project',
+    ]);
+  });
+
+  it('ask_user_questions persists confirmed depth gates for remote answers', async () => {
+    const questions = [
+      {
+        id: 'depth_verification_M003_confirm',
+        header: 'Depth Check',
+        question: 'Did I capture the depth right?',
+        options: [
+          { label: 'Yes, you got it (Recommended)', description: 'Continue with the current summary.' },
+          { label: 'Not quite', description: 'I need to clarify the depth further.' },
+        ],
+      },
+    ];
+    const calls: string[] = [];
+    const writeGate = {
+      isGateQuestionId(questionId: string) {
+        return questionId.startsWith('depth_verification_');
+      },
+      isDepthConfirmationAnswer(selected: unknown, options?: Array<{ label?: string }>) {
+        return selected === options?.[0]?.label;
+      },
+      setPendingGate(gateId: string, basePath: string) {
+        calls.push(`pending:${gateId}:${basePath}`);
+      },
+      markApprovalGateVerified(gateId?: string | null, basePath?: string) {
+        calls.push(`approval:${gateId}:${basePath}`);
+      },
+      markDepthVerified(milestoneId?: string | null, basePath?: string) {
+        calls.push(`depth:${milestoneId}:${basePath}`);
+      },
+      clearPendingGate(basePath: string) {
+        calls.push(`clear:${basePath}`);
+      },
+      extractDepthVerificationMilestoneId(questionId: string) {
+        return questionId.match(/_(M\d+)_/)?.[1] ?? null;
+      },
+    };
+
+    const result = await askUserQuestionsHandler(questions, undefined, {
+      async elicitInput() {
+        return { action: 'cancel' };
+      },
+      isRemoteConfigured() {
+        return true;
+      },
+      async tryRemoteQuestions() {
+        return {
+          content: [{ type: 'text', text: 'remote response' }],
+          details: {
+            response: {
+              endInterview: false,
+              answers: {
+                depth_verification_M003_confirm: {
+                  selected: 'Yes, you got it (Recommended)',
+                  notes: '',
+                },
+              },
+            },
+          },
+        };
+      },
+      writeGate,
+      writeGateBasePath: '/tmp/gsd-project',
+    });
+
+    assert.equal('isError' in result && result.isError, false);
+    assert.deepEqual(calls, [
+      'pending:depth_verification_M003_confirm:/tmp/gsd-project',
+      'approval:depth_verification_M003_confirm:/tmp/gsd-project',
+      'depth:M003:/tmp/gsd-project',
+      'clear:/tmp/gsd-project',
+    ]);
+  });
+
   it('ask_user_questions falls back to remote when local elicitation is cancelled', async () => {
     const questions = [
       {

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

@@ -15,6 +15,7 @@ import { readFile, readdir } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
 import { z } from 'zod';
 import type { SessionManager } from './session-manager.js';
 import { isRemoteConfigured, tryRemoteQuestions } from './remote-questions.js';
@@ -355,6 +356,16 @@ interface AskUserQuestionsStructuredContent {
   cancelled: boolean;
 }
 
+interface AskUserQuestionsWriteGateModule {
+  isGateQuestionId(questionId: string): boolean;
+  isDepthConfirmationAnswer(selected: unknown, options?: Array<{ label?: string }>): boolean;
+  setPendingGate(gateId: string, basePath: string): void;
+  markApprovalGateVerified(gateId?: string | null, basePath?: string): void;
+  markDepthVerified(milestoneId?: string | null, basePath?: string): void;
+  clearPendingGate(basePath: string): void;
+  extractDepthVerificationMilestoneId(questionId: string): string | null;
+}
+
 const OTHER_OPTION_LABEL = 'None of the above';
 
 function normalizeAskUserQuestionsNote(value: AskUserQuestionsContentValue | undefined): string {
@@ -499,6 +510,90 @@ interface AskUserQuestionsHandlerDeps {
   elicitInput(params: AskUserQuestionsElicitRequest): Promise<AskUserQuestionsElicitResult>;
   isRemoteConfigured(): boolean;
   tryRemoteQuestions(questions: AskUserQuestion[], signal?: AbortSignal): Promise<RemoteToolResult | null>;
+  writeGate?: AskUserQuestionsWriteGateModule | null;
+  writeGateBasePath?: string;
+}
+
+let askUserQuestionsWriteGateModulePromise: Promise<AskUserQuestionsWriteGateModule | null> | null = null;
+
+function isAskUserQuestionsWriteGateModule(value: unknown): value is AskUserQuestionsWriteGateModule {
+  if (!value || typeof value !== 'object') return false;
+  const module = value as Record<string, unknown>;
+  return (
+    typeof module['isGateQuestionId'] === 'function' &&
+    typeof module['isDepthConfirmationAnswer'] === 'function' &&
+    typeof module['setPendingGate'] === 'function' &&
+    typeof module['markApprovalGateVerified'] === 'function' &&
+    typeof module['markDepthVerified'] === 'function' &&
+    typeof module['clearPendingGate'] === 'function' &&
+    typeof module['extractDepthVerificationMilestoneId'] === 'function'
+  );
+}
+
+async function loadAskUserQuestionsWriteGateModule(): Promise<AskUserQuestionsWriteGateModule | null> {
+  if (!askUserQuestionsWriteGateModulePromise) {
+    askUserQuestionsWriteGateModulePromise = (async () => {
+      const modulePath = process.env.GSD_WORKFLOW_WRITE_GATE_MODULE?.trim();
+      if (!modulePath) return null;
+      try {
+        if (/^[a-z]{2,}:/i.test(modulePath) && !modulePath.startsWith('file:')) {
+          throw new Error('GSD_WORKFLOW_WRITE_GATE_MODULE only supports file: URLs or filesystem paths.');
+        }
+        const baseRoot = process.env.GSD_WORKFLOW_PROJECT_ROOT?.trim() || process.cwd();
+        const specifier = modulePath.startsWith('file:') ? modulePath : pathToFileURL(resolve(baseRoot, modulePath)).href;
+        const loaded = await import(specifier);
+        return isAskUserQuestionsWriteGateModule(loaded) ? loaded : null;
+      } catch (err) {
+        console.warn(`[gsd:mcp] ask_user_questions write-gate integration unavailable: ${formatErrorMessage(err)}`);
+        return null;
+      }
+    })();
+  }
+  return askUserQuestionsWriteGateModulePromise;
+}
+
+function askUserQuestionsWriteGateBasePath(deps: AskUserQuestionsHandlerDeps): string {
+  return deps.writeGateBasePath ?? process.env.GSD_WORKFLOW_PROJECT_ROOT?.trim() ?? process.cwd();
+}
+
+async function resolveAskUserQuestionsWriteGate(deps: AskUserQuestionsHandlerDeps): Promise<AskUserQuestionsWriteGateModule | null> {
+  if (deps.writeGate !== undefined) return deps.writeGate;
+  return loadAskUserQuestionsWriteGateModule();
+}
+
+async function recordAskUserQuestionsPendingGate(
+  questions: AskUserQuestion[],
+  deps: AskUserQuestionsHandlerDeps,
+): Promise<void> {
+  const writeGate = await resolveAskUserQuestionsWriteGate(deps);
+  if (!writeGate) return;
+
+  const basePath = askUserQuestionsWriteGateBasePath(deps);
+  for (const question of questions) {
+    if (writeGate.isGateQuestionId(question.id)) {
+      writeGate.setPendingGate(question.id, basePath);
+    }
+  }
+}
+
+async function recordAskUserQuestionsGateResult(
+  structured: AskUserQuestionsStructuredContent,
+  deps: AskUserQuestionsHandlerDeps,
+): Promise<void> {
+  if (structured.cancelled || !structured.response) return;
+  const writeGate = await resolveAskUserQuestionsWriteGate(deps);
+  if (!writeGate) return;
+
+  const basePath = askUserQuestionsWriteGateBasePath(deps);
+  for (const question of structured.questions) {
+    if (!writeGate.isGateQuestionId(question.id)) continue;
+    const selected = structured.response.answers[question.id]?.selected;
+    if (!writeGate.isDepthConfirmationAnswer(selected, question.options)) continue;
+
+    writeGate.markApprovalGateVerified(question.id, basePath);
+    writeGate.markDepthVerified(writeGate.extractDepthVerificationMilestoneId(question.id), basePath);
+    writeGate.clearPendingGate(basePath);
+  }
 }
 
 function isLocalElicitFallbackError(err: unknown): boolean {
@@ -539,6 +634,7 @@ export async function askUserQuestionsHandler(
   try {
     const validationError = validateAskUserQuestionsPayload(questions);
     if (validationError) return errorContent(validationError);
+    await recordAskUserQuestionsPendingGate(questions, deps);
 
     // Local-first: try the MCP host's elicitation channel (Claude Code,
     // Cursor, etc.) before any configured remote channel. A misconfigured
@@ -556,6 +652,7 @@ export async function askUserQuestionsHandler(
           response: buildAskUserQuestionsRoundResult(questions, elicitation),
           cancelled: false,
         };
+        await recordAskUserQuestionsGateResult(structured, deps);
         return {
           content: [{ type: 'text' as const, text: formatAskUserQuestionsElicitResult(questions, elicitation) }],
           structuredContent: structured as unknown as Record<string, unknown>,
@@ -612,11 +709,12 @@ export async function askUserQuestionsHandler(
               response: details!['response'] as AskUserQuestionsRoundResult,
               cancelled: false,
             }
-          : {
+            : {
               questions,
               response: null,
               cancelled: true,
             };
+        await recordAskUserQuestionsGateResult(acceptedStructured, deps);
         return {
           content: [{ type: 'text' as const, text: remoteResult.content[0]?.text ?? '' }],
           structuredContent: acceptedStructured as unknown as Record<string, unknown>,

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

@@ -9,7 +9,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve, join, delimiter } from 'node:path';
 import { RpcClient } from '@gsd-build/rpc-client';
-import type { SdkAgentEvent, RpcInitResult, RpcCostUpdateEvent, RpcExtensionUIRequest } from '@gsd-build/rpc-client';
+import type { SdkAgentEvent, RpcInitResult, RpcCostUpdateEvent, RpcExtensionUIRequest } from '@gsd-build/contracts';
 import type {
   ManagedSession,
   ExecuteOptions,
@@ -391,7 +391,7 @@ function extractBlocker(event: SdkAgentEvent): PendingBlocker {
   const uiEvent = event as unknown as RpcExtensionUIRequest;
   return {
     id: String(uiEvent.id ?? ''),
-    method: String(uiEvent.method ?? ''),
+    method: uiEvent.method,
     message: String((uiEvent as Record<string, unknown>).title ?? (uiEvent as Record<string, unknown>).message ?? ''),
     event: uiEvent,
   };

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

@@ -2,7 +2,12 @@
  * MCP Server types — session lifecycle and orchestration.
  */
 
-import type { RpcClient, SdkAgentEvent, RpcCostUpdateEvent, RpcExtensionUIRequest } from '@gsd-build/rpc-client';
+import type { RpcClient } from '@gsd-build/rpc-client';
+import type {
+  McpPendingBlocker as PendingBlocker,
+  RpcCostUpdateEvent,
+  SdkAgentEvent,
+} from '@gsd-build/contracts';
 
 // ---------------------------------------------------------------------------
 // Session Status
@@ -46,23 +51,7 @@ export interface ManagedSession {
   unsubscribe?: () => void;
 }
 
-// ---------------------------------------------------------------------------
-// Pending Blocker
-// ---------------------------------------------------------------------------
-
-export interface PendingBlocker {
-  /** The extension_ui_request id */
-  id: string;
-
-  /** The request method (e.g. 'select', 'confirm', 'input') */
-  method: string;
-
-  /** Human-readable message or title */
-  message: string;
-
-  /** Full event payload for inspection */
-  event: RpcExtensionUIRequest;
-}
+export type { PendingBlocker };
 
 // ---------------------------------------------------------------------------
 // Cost Accumulator (K004 — cumulative-max)

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

@@ -7,6 +7,7 @@ import { homedir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { z } from "zod";
+import { WORKFLOW_TOOL_NAMES as CONTRACT_WORKFLOW_TOOL_NAMES } from "@gsd-build/contracts";
 
 import { logAliasUsage } from "./alias-telemetry.js";
 
@@ -662,46 +663,7 @@ interface McpToolServer {
   ): unknown;
 }
 
-export const WORKFLOW_TOOL_NAMES = [
-  "gsd_decision_save",
-  "gsd_save_decision",
-  "gsd_requirement_update",
-  "gsd_update_requirement",
-  "gsd_requirement_save",
-  "gsd_save_requirement",
-  "gsd_milestone_generate_id",
-  "gsd_generate_milestone_id",
-  "gsd_plan_milestone",
-  "gsd_plan_slice",
-  "gsd_plan_task",
-  "gsd_task_plan",
-  "gsd_replan_slice",
-  "gsd_slice_replan",
-  "gsd_slice_complete",
-  "gsd_complete_slice",
-  "gsd_skip_slice",
-  "gsd_complete_milestone",
-  "gsd_milestone_complete",
-  "gsd_validate_milestone",
-  "gsd_milestone_validate",
-  "gsd_reassess_roadmap",
-  "gsd_roadmap_reassess",
-  "gsd_save_gate_result",
-  "gsd_summary_save",
-  "gsd_task_complete",
-  "gsd_complete_task",
-  "gsd_milestone_status",
-  "gsd_journal_query",
-  "gsd_exec",
-  "gsd_exec_search",
-  "gsd_resume",
-  // ADR-013 step 3: memory-store tools exposed to external MCP clients.
-  // gsd_memory_graph is namespaced to avoid collision with the existing
-  // gsd_graph tool (project knowledge graph from .gsd/ artifacts).
-  "gsd_capture_thought",
-  "gsd_memory_query",
-  "gsd_memory_graph",
-] as const;
+export const WORKFLOW_TOOL_NAMES = CONTRACT_WORKFLOW_TOOL_NAMES;
 
 const DEFAULT_WORKFLOW_OP_TIMEOUT_MS = 5 * 60 * 1000;