fix(mcp-server): suppress dispatch-ready execution while gated (#1422)

[JeremyDev87]

Closes #1422

Summary

• When executionGate.gated=true, parse_mode response now suppresses expensive specialist dispatch metadata so clients cannot proceed with costly execution during clarification
• dispatchReady and executionPlan are fully removed from gated responses
• parallelAgentsRecommendation.dispatch is downgraded from "auto"/"recommend" to "deferred"
• Specialist names and hints are preserved for transparency (deferred, not hidden)
• When the gate opens (ungated), all metadata passes through unchanged

Changes

• execution-gate.ts: Added suppressDispatchWhileGated() pure function with GatedResponseFields/SuppressedResponseFields generic types
• mode.handler.ts: Wired suppression into response assembly — applied after evaluateExecutionGate() but before createJsonResponse()
• execution-gate.spec.ts: 14 new tests covering gated suppression, ungated pass-through, immutability, and edge cases
• mode.handler.spec.ts: Updated 8 existing dispatch/execution tests to bypass clarification gate with question_budget: 0 (these tests target dispatch mechanics, not clarification behavior)

Test plan

• 14 new unit tests for suppressDispatchWhileGated (gated/ungated/undefined gate)
• All 6185 existing tests pass (0 regressions)
• TypeScript type-check clean (tsc --noEmit)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
codingbuddy-landing	Ready	Preview, Comment	Apr 7, 2026 9:50am

[JeremyDev87]

Review: REQUEST CHANGES

CI Status: FAIL

prettier-check failed on all 3 modified files:

• src/mcp/handlers/execution-gate.spec.ts
• src/mcp/handlers/execution-gate.ts
• src/mcp/handlers/mode.handler.ts

All other CI checks pass (build, type-check, lint, security, unit-test).

Spec Compliance (#1422): PASS

All 4 acceptance criteria verified:

Criterion	Status
gated=true suppresses immediate specialist execution	PASS — dispatchReady fully removed, executionPlan fully removed, dispatch downgraded to "deferred"
Deferred specialists visible for transparency	PASS — specialist names and hint preserved in parallelAgentsRecommendation
Gate open restores normal dispatch metadata	PASS — ungated path returns fields unchanged (reference equality verified)
Tests prove gated responses don't leak payloads	PASS — 14 new tests cover gated suppression, ungated pass-through, immutability, and edge cases

Issues Found

[MEDIUM] Prettier formatting failure — CI blocker
Files: execution-gate.spec.ts, execution-gate.ts, mode.handler.ts
Issue: All 3 modified files fail the prettier-check CI job. This blocks merge.
Fix: Run yarn workspace codingbuddy format:write on the 3 files and push.

[LOW] Loose typing on GatedParallelRecommendation.dispatch
File: execution-gate.ts (new interface around line 110)
Issue: dispatch?: string accepts any string, but the actual domain values are "auto" | "recommend" | "deferred" | "skip". A union type would catch invalid values at compile time.
Fix: Consider dispatch?: 'auto' | 'recommend' | 'deferred' | 'skip' — though the current loose typing intentionally avoids coupling to the parent module's types, so this is acceptable if deliberate.

[LOW] SuppressedResponseFields type alias is structurally identical to GatedResponseFields
File: execution-gate.ts (around line 134)
Issue: The alias adds no structural differentiation under TypeScript's structural typing. It serves only as documentation.
Fix: No action required — the semantic naming is reasonable for readability. Noting for awareness only.

Quality Assessment

• Security: No issues. Pure function, no side effects, no secrets.
• Type Safety: CI type-check passes. No any types. Generics used well for decoupling.
• Immutability: Verified — function creates new objects, test explicitly asserts no mutation of inputs.
• Integration: mode.handler.ts wiring is clean — suppression applied after gate evaluation, before response assembly. Correct ordering per spec.
• Tests: 14 new tests are comprehensive. 8 existing tests updated with question_budget: 0 to isolate dispatch mechanics from clarification behavior — appropriate.

Recommendation: REQUEST CHANGES

The only blocking issue is the prettier formatting failure. The implementation itself is solid — clean pure function, proper immutability, comprehensive tests, and full spec compliance. Fix formatting and this is ready to merge.

[JeremyDev87]

Re-Review: APPROVE

CI Status: PASS (all checks green including prettier-check)

Previous Issues: All resolved

• MEDIUM (prettier): ✅ Fixed — all 3 files pass prettier --check
• LOW (dispatch typing): Noted — acceptable as-is
• LOW (type alias): Noted — semantic naming, no action needed

New Issues Found: 0

Recommendation: APPROVE — Critical 0, High 0, Medium 0. Ready to merge.