feat(mcp-server): gate expensive specialist execution until clarification confirmed

Closes #1378

Delay specialist dispatch and tool-heavy execution until the request is
clarified enough to justify the cost. Builds on Clarification Gate
(#1371) and Staged Planning (#1372).

Gating rules (evaluated in order):
  1. planReady=true                → ungated (full dispatch)
  2. clarificationNeeded=true      → gated (ambiguous)
  3. currentStage in {discover,design} → gated (still exploring)
  4. Otherwise                     → ungated

New response field in PLAN/AUTO parse_mode response:
  executionGate: {
    gated: boolean
    reason: string
    unblockCondition?: string
    deferredSpecialists?: string[]
  }

When gated, specialists that would normally be dispatched are preserved
in deferredSpecialists for later dispatch after the gate opens.

Backward-compatible: clear prompts (planReady=true) are never gated.
ACT/EVAL modes omit executionGate entirely.

Tests: 14 unit + 6 integration (gated/ungated/budget-exhausted/
ACT-EVAL skip/AUTO mode).

Author: JeremyDev87

apps/mcp-server/src/mcp/handlers/execution-gate.spec.ts

@@ -0,0 +1,276 @@
+import { describe, it, expect } from 'vitest';
+import { evaluateExecutionGate, type ExecutionGateInput } from './execution-gate';
+import type { ClarificationMetadata } from './clarification-gate';
+import type { PlanningStageMetadata } from './planning-stage';
+
+// ---------------------------------------------------------------------------
+// Helper factories
+// ---------------------------------------------------------------------------
+
+function ambiguousClarification(): ClarificationMetadata {
+  return {
+    clarificationNeeded: true,
+    planReady: false,
+    questionBudget: 2,
+    nextQuestion: 'What should change?',
+    clarificationTopics: ['vague-intent'],
+  };
+}
+
+function clearClarification(): ClarificationMetadata {
+  return {
+    clarificationNeeded: false,
+    planReady: true,
+    questionBudget: 3,
+  };
+}
+
+function budgetExhaustedClarification(): ClarificationMetadata {
+  return {
+    clarificationNeeded: false,
+    planReady: true,
+    questionBudget: 0,
+    assumptionNote: 'Proceeding with assumptions.',
+  };
+}
+
+function discoverStage(): PlanningStageMetadata {
+  return {
+    currentStage: 'discover',
+    stageDescription: 'Discover: Surface questions...',
+    nextStage: 'design',
+    stageTransitionHint: 'Answer clarification to proceed.',
+    recommendedAgent: 'solution-architect',
+    recommendedSkill: 'brainstorming',
+  };
+}
+
+function designStage(): PlanningStageMetadata {
+  return {
+    currentStage: 'design',
+    stageDescription: 'Design: Synthesize approaches...',
+    nextStage: 'plan',
+    stageTransitionHint: 'Confirm approach to proceed.',
+    recommendedAgent: 'solution-architect',
+  };
+}
+
+function planStage(): PlanningStageMetadata {
+  return {
+    currentStage: 'plan',
+    stageDescription: 'Plan: Produce implementation plan.',
+    recommendedAgent: 'technical-planner',
+    recommendedSkill: 'writing-plans',
+  };
+}
+
+const SAMPLE_SPECIALISTS = [
+  'security-specialist',
+  'performance-specialist',
+  'code-quality-specialist',
+];
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('execution-gate', () => {
+  describe('evaluateExecutionGate', () => {
+    // ------------------------------------------------------------------
+    // Gated scenarios
+    // ------------------------------------------------------------------
+
+    describe('gated (ambiguous / early stage)', () => {
+      it('gates when clarificationNeeded=true', () => {
+        const input: ExecutionGateInput = {
+          clarification: ambiguousClarification(),
+          specialists: SAMPLE_SPECIALISTS,
+        };
+
+        const result = evaluateExecutionGate(input);
+
+        expect(result.gated).toBe(true);
+        expect(result.reason).toContain('ambiguous');
+        expect(result.unblockCondition).toBeTruthy();
+        expect(result.deferredSpecialists).toEqual(SAMPLE_SPECIALISTS);
+      });
+
+      it('gates when currentStage=discover', () => {
+        const input: ExecutionGateInput = {
+          clarification: { clarificationNeeded: false, planReady: false },
+          planningStage: discoverStage(),
+          specialists: SAMPLE_SPECIALISTS,
+        };
+
+        const result = evaluateExecutionGate(input);
+
+        expect(result.gated).toBe(true);
+        expect(result.reason).toContain('discover');
+        expect(result.unblockCondition).toContain('Design');
+      });
+
+      it('gates when currentStage=design', () => {
+        const input: ExecutionGateInput = {
+          clarification: { clarificationNeeded: false, planReady: false },
+          planningStage: designStage(),
+          specialists: SAMPLE_SPECIALISTS,
+        };
+
+        const result = evaluateExecutionGate(input);
+
+        expect(result.gated).toBe(true);
+        expect(result.reason).toContain('design');
+        expect(result.unblockCondition).toContain('Plan');
+      });
+
+      it('defers specialists list when gated', () => {
+        const input: ExecutionGateInput = {
+          clarification: ambiguousClarification(),
+          specialists: ['security-specialist', 'accessibility-specialist'],
+        };
+
+        const result = evaluateExecutionGate(input);
+
+        expect(result.deferredSpecialists).toEqual([
+          'security-specialist',
+          'accessibility-specialist',
+        ]);
+      });
+
+      it('omits deferredSpecialists when no specialists provided', () => {
+        const input: ExecutionGateInput = {
+          clarification: ambiguousClarification(),
+        };
+
+        const result = evaluateExecutionGate(input);
+
+        expect(result.gated).toBe(true);
+        expect(result.deferredSpecialists).toBeUndefined();
+      });
+
+      it('omits deferredSpecialists when specialists list is empty', () => {
+        const input: ExecutionGateInput = {
+          clarification: ambiguousClarification(),
+          specialists: [],
+        };
+
+        const result = evaluateExecutionGate(input);
+
+        expect(result.gated).toBe(true);
+        expect(result.deferredSpecialists).toBeUndefined();
+      });
+    });
+
+    // ------------------------------------------------------------------
+    // Ungated scenarios
+    // ------------------------------------------------------------------
+
+    describe('ungated (clear / plan stage)', () => {
+      it('does not gate when planReady=true', () => {
+        const input: ExecutionGateInput = {
+          clarification: clearClarification(),
+          specialists: SAMPLE_SPECIALISTS,
+        };
+
+        const result = evaluateExecutionGate(input);
+
+        expect(result.gated).toBe(false);
+        expect(result.reason).toContain('clear');
+        expect(result.unblockCondition).toBeUndefined();
+        expect(result.deferredSpecialists).toBeUndefined();
+      });
+
+      it('does not gate when currentStage=plan', () => {
+        const input: ExecutionGateInput = {
+          clarification: clearClarification(),
+          planningStage: planStage(),
+          specialists: SAMPLE_SPECIALISTS,
+        };
+
+        const result = evaluateExecutionGate(input);
+
+        expect(result.gated).toBe(false);
+      });
+
+      it('does not gate when budget is exhausted (planReady forced)', () => {
+        const input: ExecutionGateInput = {
+          clarification: budgetExhaustedClarification(),
+          specialists: SAMPLE_SPECIALISTS,
+        };
+
+        const result = evaluateExecutionGate(input);
+
+        expect(result.gated).toBe(false);
+      });
+
+      it('planReady=true overrides discover stage', () => {
+        const input: ExecutionGateInput = {
+          clarification: clearClarification(),
+          planningStage: discoverStage(),
+          specialists: SAMPLE_SPECIALISTS,
+        };
+
+        const result = evaluateExecutionGate(input);
+
+        // planReady takes precedence over stage
+        expect(result.gated).toBe(false);
+      });
+
+      it('planReady=true overrides design stage', () => {
+        const input: ExecutionGateInput = {
+          clarification: clearClarification(),
+          planningStage: designStage(),
+          specialists: SAMPLE_SPECIALISTS,
+        };
+
+        const result = evaluateExecutionGate(input);
+
+        expect(result.gated).toBe(false);
+      });
+    });
+
+    // ------------------------------------------------------------------
+    // Priority / edge cases
+    // ------------------------------------------------------------------
+
+    describe('priority and edge cases', () => {
+      it('clarificationNeeded takes priority over planningStage', () => {
+        const input: ExecutionGateInput = {
+          clarification: ambiguousClarification(),
+          planningStage: planStage(), // even though stage says plan
+          specialists: SAMPLE_SPECIALISTS,
+        };
+
+        const result = evaluateExecutionGate(input);
+
+        // clarificationNeeded=true is checked before stage
+        expect(result.gated).toBe(true);
+        expect(result.reason).toContain('ambiguous');
+      });
+
+      it('works without planningStage metadata', () => {
+        const input: ExecutionGateInput = {
+          clarification: clearClarification(),
+          // no planningStage
+        };
+
+        const result = evaluateExecutionGate(input);
+
+        expect(result.gated).toBe(false);
+      });
+
+      it('does not mutate the input specialists array', () => {
+        const specialists = ['a', 'b', 'c'];
+        const input: ExecutionGateInput = {
+          clarification: ambiguousClarification(),
+          specialists,
+        };
+
+        const result = evaluateExecutionGate(input);
+
+        expect(result.deferredSpecialists).toEqual(['a', 'b', 'c']);
+        expect(result.deferredSpecialists).not.toBe(specialists); // different reference
+      });
+    });
+  });
+});

apps/mcp-server/src/mcp/handlers/execution-gate.ts

@@ -0,0 +1,117 @@
+/**
+ * Execution Gate — delay expensive specialist dispatch until clarification
+ * is confirmed (#1378).
+ *
+ * When a request is still ambiguous (discover/design stage or
+ * clarificationNeeded=true), dispatching specialists and tool-heavy
+ * execution creates unnecessary cost and noise. This gate holds
+ * expensive work until the user has confirmed direction.
+ *
+ * Like the Clarification Gate and Planning Stage, this module is
+ * intentionally pure and free of NestJS dependencies.
+ */
+
+import type { ClarificationMetadata } from './clarification-gate';
+import type { PlanningStageMetadata } from './planning-stage';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Execution gate metadata included in the PLAN/AUTO parse_mode response. */
+export interface ExecutionGate {
+  /** True when expensive execution (specialist dispatch, tool-heavy work) is held. */
+  gated: boolean;
+  /** Human-readable reason for the current gate state. */
+  reason: string;
+  /** What must happen for the gate to open. Undefined when not gated. */
+  unblockCondition?: string;
+  /** Specialists that would have been dispatched but are deferred. Present only when gated. */
+  deferredSpecialists?: string[];
+}
+
+/** Inputs consumed by the execution gate evaluator. */
+export interface ExecutionGateInput {
+  /** Clarification metadata from the Clarification Gate (#1371). */
+  clarification: ClarificationMetadata;
+  /** Planning stage metadata from the Stage Router (#1372). */
+  planningStage?: PlanningStageMetadata;
+  /** Specialists that would normally be dispatched. */
+  specialists?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const GATED_STAGES = new Set(['discover', 'design']);
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate whether expensive execution should be gated based on
+ * clarification status and planning stage.
+ *
+ * Gating rules (evaluated in order):
+ * 1. `planReady=true` → ungated (request is clear enough to execute).
+ * 2. `clarificationNeeded=true` → gated (ambiguous).
+ * 3. `currentStage` in {discover, design} → gated (still exploring).
+ * 4. Otherwise → ungated.
+ */
+export function evaluateExecutionGate(input: ExecutionGateInput): ExecutionGate {
+  const { clarification, planningStage, specialists } = input;
+
+  // 1. planReady → always ungated
+  if (clarification.planReady) {
+    return {
+      gated: false,
+      reason: 'Request is clear — full specialist dispatch permitted.',
+    };
+  }
+
+  // 2. clarificationNeeded → gated
+  if (clarification.clarificationNeeded) {
+    return buildGatedResult(
+      'Request is ambiguous — specialist dispatch deferred until clarification is resolved.',
+      'Resolve clarification questions or provide an explicit override (e.g., "just do it").',
+      specialists,
+    );
+  }
+
+  // 3. Stage-based gating (discover/design)
+  if (planningStage && GATED_STAGES.has(planningStage.currentStage)) {
+    const stageName = planningStage.currentStage;
+    return buildGatedResult(
+      `Currently in ${stageName} stage — specialist dispatch deferred until plan stage.`,
+      stageName === 'discover'
+        ? 'Confirm direction to proceed through Design to Plan.'
+        : 'Confirm approach to proceed to Plan.',
+      specialists,
+    );
+  }
+
+  // 4. Fallback — ungated
+  return {
+    gated: false,
+    reason: 'Execution permitted — no gating conditions active.',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function buildGatedResult(
+  reason: string,
+  unblockCondition: string,
+  specialists?: string[],
+): ExecutionGate {
+  return {
+    gated: true,
+    reason,
+    unblockCondition,
+    ...(specialists?.length && { deferredSpecialists: [...specialists] }),
+  };
+}