@hegemonart/get-design-done 1.27.6 → 1.28.0

package/scripts/mcp-servers/gdd-mcp/schemas/gdd_status.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gdd_status",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {}
+    },
+    "output": {
+      "type": "object",
+      "required": ["phase", "branch", "last_decisions", "last_completed_plans", "blocker_count"],
+      "properties": {
+        "phase": { "type": ["string", "null"] },
+        "branch": { "type": ["string", "null"] },
+        "last_decisions": { "type": "array", "items": { "type": "object" } },
+        "last_completed_plans": { "type": "array", "items": { "type": "object" } },
+        "blocker_count": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/scripts/mcp-servers/gdd-mcp/schemas/gdd_telemetry_query.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gdd_telemetry_query",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string" },
+        "since": { "type": "string", "format": "date-time" },
+        "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }
+      }
+    },
+    "output": {
+      "type": "object",
+      "required": ["events"],
+      "properties": {
+        "events": { "type": "array", "items": { "type": "object" } }
+      }
+    }
+  }
+}

package/scripts/mcp-servers/gdd-mcp/server.ts

@@ -0,0 +1,317 @@
+#!/usr/bin/env -S node --experimental-strip-types
+// scripts/mcp-servers/gdd-mcp/server.ts
+//
+// MCP server `gdd-mcp` — read-mostly project-state surface (Phase 27.7).
+// Exposes STATE.md sections, phases, decisions, plans, telemetry, intel
+// slices, and the latest reflection as typed MCP tools backed by the
+// same `scripts/lib/*` modules the CLI uses.
+//
+// Lifecycle (mirrors Phase 20 `gdd-state` server):
+//   1. Construct a low-level Server (we use the low-level surface so we
+//      can speak JSON Schema directly — the high-level McpServer wants
+//      Zod shapes, and our per-tool schemas are Draft-07 JSON.)
+//   2. Register `tools/list` — returns the registered tools with their
+//      input JSON Schemas loaded from disk. Scaffold ships with 0
+//      tools; Plan 27.7-02 populates `TOOL_MODULES` with 12 entries.
+//   3. Register `tools/call` — dispatches by name to the matching
+//      handler. Each handler returns a typed ToolResponse; the server
+//      wraps it into the MCP CallToolResult shape. Unknown tool names
+//      return `isError: true` with a structured payload.
+//   4. Attach StdioServerTransport; await connect. NO port allocation
+//      (D-05 stdio-only).
+//   5. On SIGINT / SIGTERM: close the transport, exit 0. Re-entrant
+//      shutdown is guarded with a module-level `SHUTTING_DOWN` flag.
+//
+// Project-root discovery (D-05): `resolveProjectRoot()` lives in
+// `./tools/shared.ts` and walks up from `process.cwd()` looking for
+// `.design/` OR `.planning/` OR `.claude-plugin/plugin.json`. Server
+// infrastructure is allowed to import `node:fs`/`node:path` directly;
+// only individual TOOL files are bound by the thin-wrapper rule (D-06).
+//
+// Invariant: handler throws are contained. The dispatcher wraps every
+// call in a try/catch that funnels through `toToolError()` — the MCP
+// harness never sees an uncaught throw from our tools.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { toToolError } from '../../lib/gdd-errors/classification.ts';
+import { TOOL_MODULES, type ToolModule } from './tools/index.ts';
+
+/** Server metadata advertised on initialize. */
+export const SERVER_NAME = 'gdd-mcp';
+export const SERVER_VERSION = '1.27.7';
+
+/**
+ * Resolve this module's directory. We deliberately avoid `import.meta.url`
+ * (not permitted by our tsconfig's Node16+CommonJS-compatible module
+ * resolution) and `__dirname` (not portable under strip-types ESM).
+ *
+ * Strategy: when this module is invoked as a script, `process.argv[1]`
+ * points at this file; resolve its dirname. When it is imported for
+ * tests, we fall back to walking from `process.cwd()` — tests run
+ * from the repo root by convention, so `scripts/mcp-servers/gdd-mcp`
+ * resolves reliably. Both branches are canonicalized against the
+ * on-disk tools directory.
+ */
+function here(): string {
+  const expectedRel = join('scripts', 'mcp-servers', 'gdd-mcp');
+  // Script invocation: process.argv[1] === .../server.ts (or a shim).
+  const entry = process.argv[1];
+  if (typeof entry === 'string' && entry.length > 0) {
+    const entryDir = dirname(resolve(entry));
+    if (existsSync(join(entryDir, 'tools', 'index.ts'))) {
+      return entryDir;
+    }
+  }
+  // Library-import path (tests): walk cwd forward.
+  const candidate = resolve(process.cwd(), expectedRel);
+  if (existsSync(join(candidate, 'tools', 'index.ts'))) {
+    return candidate;
+  }
+  // Last-resort: return the expected path even if it does not exist —
+  // the subsequent readFileSync() call will produce a clear error.
+  return candidate;
+}
+
+/** Eager cache of input schemas keyed by tool name. We load them once at
+ *  startup so a tool-call handler never hits the filesystem in the hot
+ *  path; subsequent schema edits (JSON file on disk) require a server
+ *  restart, which matches every other part of the pipeline.
+ *
+ *  Scaffold ships with 0 tools — loadTools() returns []. Plan 27.7-02
+ *  adds 12 tool modules, each with its own `schemaPath` pointing into
+ *  `scripts/mcp-servers/gdd-mcp/schemas/`. */
+interface LoadedTool extends ToolModule {
+  inputSchema: Record<string, unknown>;
+}
+
+function loadTools(): LoadedTool[] {
+  const baseDir = here();
+  return TOOL_MODULES.map((m) => {
+    const absPath = join(baseDir, 'tools', m.schemaPath);
+    const raw = readFileSync(absPath, 'utf8');
+    const parsed = JSON.parse(raw) as {
+      properties?: {
+        input?: { type?: string; properties?: Record<string, unknown> };
+      };
+    };
+    // The per-tool schema files are Draft-07 wrappers shaped as:
+    //   { type: "object", properties: { input: {...}, output: {...} } }
+    // MCP's tools/list advertises only the INPUT half. We project
+    // `properties.input` here; when the schema is malformed we fall
+    // back to an open object so the tool is still listable.
+    const rawInput = parsed.properties?.input;
+    const inputSchema: Record<string, unknown> =
+      rawInput !== undefined && typeof rawInput === 'object'
+        ? (rawInput as Record<string, unknown>)
+        : { type: 'object' };
+    if (!('type' in inputSchema)) inputSchema['type'] = 'object';
+    return { ...m, inputSchema };
+  });
+}
+
+/**
+ * Tool descriptions — short, scannable, lifted from the plan. Skill
+ * prose uses these verbatim when suggesting a tool to the model.
+ *
+ * Plan 27.7-02 populates 12 entries — one per tool name in the canonical
+ * 12-tool list.
+ */
+export const TOOL_DESCRIPTIONS: Record<string, string> = {
+  gdd_status:
+    'gdd_status: current cycle phase, branch, last-3 decisions, last-3 completed plans, blocker count.',
+  gdd_phase_current:
+    'gdd_phase_current: STATE.md <position> block (phase, stage, task_progress, status).',
+  gdd_phases_list:
+    'gdd_phases_list: parsed ROADMAP.md overview (phase number, name, target version, shipped/planned).',
+  gdd_plans_list:
+    'gdd_plans_list: plans tracked in STATE.md must_haves (optionally filtered by input.phase).',
+  gdd_decisions_list:
+    'gdd_decisions_list: decisions from STATE.md (optionally filtered by input.status).',
+  gdd_intel_get:
+    'gdd_intel_get: read a slice from .design/intel/ (input.slice_id required); directory_not_found if absent.',
+  gdd_telemetry_query:
+    'gdd_telemetry_query: typed reader over .design/telemetry/*.jsonl with type/since/limit filters.',
+  gdd_cycle_recap:
+    'gdd_cycle_recap: diff current STATE against latest .design/snapshots/ snapshot; directory_not_found if absent.',
+  gdd_reflections_latest:
+    'gdd_reflections_latest: newest .design/reflections/ file (excerpt <= 4 KB); directory_not_found if absent.',
+  gdd_learnings_digest:
+    'gdd_learnings_digest: aggregate last N reflections into a compact digest (<= 5 KB).',
+  gdd_events_tail:
+    'gdd_events_tail: last-N events from .design/telemetry/events.jsonl with optional type filter.',
+  gdd_health:
+    'gdd_health: read-only mirror of gdd-health SKILL — 4 checks (CLAUDE.md, .planning/, .design/, package.json).',
+};
+
+/** Human-readable annotation hints (MCP clients use these to style the
+ *  tool in UI). `readOnlyHint: true` — tells clients this tool does NOT
+ *  modify disk. v1 is read-only (D-04) so every entry is `true`. */
+export const TOOL_READONLY: Record<string, boolean> = {
+  gdd_status: true,
+  gdd_phase_current: true,
+  gdd_phases_list: true,
+  gdd_plans_list: true,
+  gdd_decisions_list: true,
+  gdd_intel_get: true,
+  gdd_telemetry_query: true,
+  gdd_cycle_recap: true,
+  gdd_reflections_latest: true,
+  gdd_learnings_digest: true,
+  gdd_events_tail: true,
+  gdd_health: true,
+};
+
+/**
+ * Build the MCP server. The tools list and call handlers are the only
+ * two request handlers we register; everything else (initialize, ping,
+ * cancellation, shutdown) is handled internally by the Protocol class.
+ */
+export function buildServer(): Server {
+  const tools = loadTools();
+  const byName: Map<string, LoadedTool> = new Map();
+  for (const t of tools) byName.set(t.name, t);
+
+  const server = new Server(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    {
+      capabilities: { tools: {} },
+    },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: tools.map((t) => {
+        const description = TOOL_DESCRIPTIONS[t.name] ?? t.name;
+        const readOnly = TOOL_READONLY[t.name] ?? true;
+        return {
+          name: t.name,
+          description,
+          inputSchema: t.inputSchema as {
+            type: 'object';
+            properties?: Record<string, unknown>;
+            required?: string[];
+          },
+          annotations: {
+            readOnlyHint: readOnly,
+            destructiveHint: !readOnly,
+            idempotentHint: false,
+          },
+        };
+      }),
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name: toolName, arguments: args } = req.params;
+    const tool = byName.get(toolName);
+    if (tool === undefined) {
+      // Unknown tool — return as CallToolResult isError=true so the
+      // client gets a structured error rather than a JSON-RPC error.
+      const payload = toToolError(
+        new Error(`unknown tool: ${toolName}`),
+      );
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify({ success: false, error: payload.error }),
+          },
+        ],
+        structuredContent: { success: false, error: payload.error },
+      };
+    }
+
+    let response;
+    try {
+      response = await tool.handle(args ?? {});
+    } catch (err) {
+      // Defensive catch — handlers shouldn't throw, but if one does
+      // we translate rather than crashing the server.
+      const payload = toToolError(err);
+      response = { success: false as const, error: payload.error };
+    }
+
+    const text = JSON.stringify(response);
+    if (response.success === true) {
+      return {
+        content: [{ type: 'text' as const, text }],
+        structuredContent: response as unknown as Record<string, unknown>,
+      };
+    }
+    return {
+      isError: true,
+      content: [{ type: 'text' as const, text }],
+      structuredContent: response as unknown as Record<string, unknown>,
+    };
+  });
+
+  return server;
+}
+
+/**
+ * Run the server against stdio and block until the transport closes.
+ * Called from CLI when this file is invoked as a script.
+ */
+export async function runStdio(): Promise<void> {
+  const server = buildServer();
+  const transport = new StdioServerTransport();
+
+  const shutdown = async (signal: string): Promise<void> => {
+    // Re-entrant: signal handlers can fire more than once on flaky
+    // shells. Guard with a module-level flag.
+    if (SHUTTING_DOWN) return;
+    SHUTTING_DOWN = true;
+    try {
+      await server.close();
+    } catch {
+      // best-effort; we're exiting anyway.
+    }
+    // SIGTERM / SIGINT convention: exit(0) — orderly shutdown.
+    process.exit(signal === 'SIGTERM' ? 0 : 0);
+  };
+
+  process.on('SIGINT', () => {
+    void shutdown('SIGINT');
+  });
+  process.on('SIGTERM', () => {
+    void shutdown('SIGTERM');
+  });
+
+  await server.connect(transport);
+}
+
+/** Re-entrancy guard for `shutdown()`. */
+let SHUTTING_DOWN = false;
+
+/**
+ * Are we being invoked as a script? We compare the argv[1] file path's
+ * basename to `server.ts` — test imports never match this because
+ * `node --test tests/*.ts` sets argv[1] to the test runner entry, not
+ * our file. A direct `node scripts/mcp-servers/gdd-mcp/server.ts`
+ * invocation DOES match. The Windows-safe path normalization uses
+ * `.replace(/\\/g, '/')` before the endsWith check.
+ */
+function isMain(): boolean {
+  const entry = process.argv[1];
+  if (typeof entry !== 'string' || entry.length === 0) return false;
+  return entry.replace(/\\/g, '/').endsWith('scripts/mcp-servers/gdd-mcp/server.ts');
+}
+
+if (isMain()) {
+  runStdio().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    // eslint-disable-next-line no-console
+    console.error(`[gdd-mcp] fatal: ${msg}`);
+    process.exit(1);
+  });
+}

package/scripts/mcp-servers/gdd-mcp/tools/gdd_cycle_recap.ts

@@ -0,0 +1,37 @@
+// scripts/mcp-servers/gdd-mcp/tools/gdd_cycle_recap.ts
+//
+// Plan 27.7-02. Diffs current STATE.md against the latest .design/snapshots/
+// snapshot. SnapshotNotFoundError → directory_not_found via errorResponse.
+
+import { read } from '../../../lib/gdd-state/index.ts';
+import { readLatestSnapshot } from '../../../lib/snapshot-reader/index.cjs';
+import { errorResponse, okResponse, resolveProjectRoot, resolveStatePath, type ToolResponse } from './shared.ts';
+
+export const name = 'gdd_cycle_recap';
+export const schemaPath = '../schemas/gdd_cycle_recap.schema.json';
+
+function snapCount(snap: Record<string, unknown>, key: string, fallback: string): number {
+  if (typeof snap[key] === 'number') return snap[key] as number;
+  const arr = snap[fallback];
+  return Array.isArray(arr) ? arr.length : 0;
+}
+
+export async function handle(_input: unknown): Promise<ToolResponse> {
+  try {
+    const snap = await readLatestSnapshot(resolveProjectRoot());
+    const state = await read(resolveStatePath());
+    if (snap === null) return okResponse({ since: null, diff: { state_sections: [], decisions_delta: 0, completed_plans_delta: 0 } });
+    const decisionsNow = (state.decisions ?? []).length;
+    const completedNow = (state.must_haves ?? []).filter((m) => m.status === 'pass').length;
+    return okResponse({
+      since: snap.since,
+      diff: {
+        state_sections: Object.keys(state),
+        decisions_delta: decisionsNow - snapCount(snap.snapshot, 'decisions_count', 'last_n_decisions'),
+        completed_plans_delta: completedNow - snapCount(snap.snapshot, 'completed_plans_count', '_unused'),
+      },
+    });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-mcp/tools/gdd_decisions_list.ts

@@ -0,0 +1,33 @@
+// scripts/mcp-servers/gdd-mcp/tools/gdd_decisions_list.ts
+//
+// Plan 27.7-02. Reads <decisions> block from STATE.md. Optional
+// input.status filter narrows the list to one DecisionStatus.
+
+import { read } from '../../../lib/gdd-state/index.ts';
+import {
+  errorResponse,
+  okResponse,
+  resolveStatePath,
+  type ToolResponse,
+} from './shared.ts';
+
+export const name = 'gdd_decisions_list';
+export const schemaPath = '../schemas/gdd_decisions_list.schema.json';
+
+interface DecisionsInput {
+  status?: string;
+}
+
+export async function handle(input: unknown): Promise<ToolResponse> {
+  try {
+    const typed = (input ?? {}) as DecisionsInput;
+    const state = await read(resolveStatePath());
+    let decisions = state.decisions ?? [];
+    if (typeof typed.status === 'string' && typed.status.length > 0) {
+      decisions = decisions.filter((d) => d.status === typed.status);
+    }
+    return okResponse({ decisions });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-mcp/tools/gdd_events_tail.ts

@@ -0,0 +1,26 @@
+// scripts/mcp-servers/gdd-mcp/tools/gdd_events_tail.ts
+//
+// Plan 27.7-02. Last-N events from .design/telemetry/events.jsonl with
+// optional type filter. Uses scripts/lib/event-stream readEvents.
+
+import { readEvents } from '../../../lib/event-stream/index.ts';
+import { errorResponse, okResponse, resolveTelemetryDir, type ToolResponse } from './shared.ts';
+
+export const name = 'gdd_events_tail';
+export const schemaPath = '../schemas/gdd_events_tail.schema.json';
+
+interface TailInput { type?: string; limit?: number; }
+
+export async function handle(input: unknown): Promise<ToolResponse> {
+  try {
+    const typed = (input ?? {}) as TailInput;
+    const limit = typeof typed.limit === 'number' && typed.limit > 0 ? typed.limit : 50;
+    const ring: unknown[] = [];
+    const opts: { path: string; type?: string } = { path: resolveTelemetryDir() + '/events.jsonl' };
+    if (typeof typed.type === 'string' && typed.type.length > 0) opts.type = typed.type;
+    for await (const ev of readEvents(opts)) { ring.push(ev); if (ring.length > limit) ring.shift(); }
+    return okResponse({ events: ring });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-mcp/tools/gdd_health.ts

@@ -0,0 +1,19 @@
+// scripts/mcp-servers/gdd-mcp/tools/gdd_health.ts
+//
+// Plan 27.7-02. Read-only mirror of skills/health/SKILL.md output via
+// scripts/lib/gsd-health-mirror/. No subprocess spawn — pure inspection.
+
+import { getHealthChecks } from '../../../lib/gsd-health-mirror/index.cjs';
+import { errorResponse, okResponse, resolveProjectRoot, type ToolResponse } from './shared.ts';
+
+export const name = 'gdd_health';
+export const schemaPath = '../schemas/gdd_health.schema.json';
+
+export async function handle(_input: unknown): Promise<ToolResponse> {
+  try {
+    const result = await getHealthChecks(resolveProjectRoot());
+    return okResponse({ checks: result.checks });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-mcp/tools/gdd_intel_get.ts

@@ -0,0 +1,32 @@
+// scripts/mcp-servers/gdd-mcp/tools/gdd_intel_get.ts
+//
+// Plan 27.7-02. Reads a .design/intel/ slice via scripts/lib/intel-store/
+// (Warning #7: NOT design-search.cjs). IntelNotFoundError surfaces
+// gracefully via errorResponse's mcp_code projection (Warning #5).
+
+import { readSlice } from '../../../lib/intel-store/index.cjs';
+import { errorResponse, okResponse, resolveProjectRoot, type ToolResponse } from './shared.ts';
+
+export const name = 'gdd_intel_get';
+export const schemaPath = '../schemas/gdd_intel_get.schema.json';
+
+interface IntelInput { slice_id: string; shape?: string[]; }
+
+export async function handle(input: unknown): Promise<ToolResponse> {
+  try {
+    const typed = (input ?? {}) as IntelInput;
+    if (typeof typed.slice_id !== 'string' || typed.slice_id.length === 0) {
+      return errorResponse(new Error('slice_id is required'));
+    }
+    const data = await readSlice(resolveProjectRoot(), typed.slice_id);
+    if (data === null) return errorResponse(new Error('slice not found: ' + typed.slice_id));
+    if (Array.isArray(typed.shape) && typed.shape.length > 0 && typeof data === 'object' && data !== null) {
+      const projected: Record<string, unknown> = {};
+      for (const k of typed.shape) if (k in (data as Record<string, unknown>)) projected[k] = (data as Record<string, unknown>)[k];
+      return okResponse({ slice_id: typed.slice_id, data: projected });
+    }
+    return okResponse({ slice_id: typed.slice_id, data: data as Record<string, unknown> });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-mcp/tools/gdd_learnings_digest.ts

@@ -0,0 +1,23 @@
+// scripts/mcp-servers/gdd-mcp/tools/gdd_learnings_digest.ts
+//
+// Plan 27.7-02. Aggregates last N reflections into a <= 5 KB digest
+// via scripts/lib/reflections-reader/.
+
+import { readNReflections, digestReflections } from '../../../lib/reflections-reader/index.cjs';
+import { errorResponse, okResponse, resolveProjectRoot, type ToolResponse } from './shared.ts';
+
+export const name = 'gdd_learnings_digest';
+export const schemaPath = '../schemas/gdd_learnings_digest.schema.json';
+
+interface DigestInput { cycles?: number; }
+
+export async function handle(input: unknown): Promise<ToolResponse> {
+  try {
+    const typed = (input ?? {}) as DigestInput;
+    const n = typeof typed.cycles === 'number' && typed.cycles > 0 ? typed.cycles : 5;
+    const refls = await readNReflections(resolveProjectRoot(), n);
+    return okResponse({ digest: digestReflections(refls), cycles_included: refls.length });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-mcp/tools/gdd_phase_current.ts

@@ -0,0 +1,29 @@
+// scripts/mcp-servers/gdd-mcp/tools/gdd_phase_current.ts
+//
+// Plan 27.7-02. Returns the <position> block from STATE.md.
+
+import { read } from '../../../lib/gdd-state/index.ts';
+import {
+  errorResponse,
+  okResponse,
+  resolveStatePath,
+  type ToolResponse,
+} from './shared.ts';
+
+export const name = 'gdd_phase_current';
+export const schemaPath = '../schemas/gdd_phase_current.schema.json';
+
+export async function handle(_input: unknown): Promise<ToolResponse> {
+  try {
+    const state = await read(resolveStatePath());
+    const p = state.position;
+    return okResponse({
+      phase: state.frontmatter.cycle ?? null,
+      stage: p?.stage ?? null,
+      task_progress: p?.task_progress ?? null,
+      status: p?.status ?? null,
+    });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-mcp/tools/gdd_phases_list.ts

@@ -0,0 +1,26 @@
+// scripts/mcp-servers/gdd-mcp/tools/gdd_phases_list.ts
+//
+// Plan 27.7-02. Parses .planning/ROADMAP.md via scripts/lib/roadmap-reader.
+
+import {
+  readRoadmapMd,
+  parsePhases,
+} from '../../../lib/roadmap-reader/index.cjs';
+import {
+  errorResponse,
+  okResponse,
+  resolveProjectRoot,
+  type ToolResponse,
+} from './shared.ts';
+
+export const name = 'gdd_phases_list';
+export const schemaPath = '../schemas/gdd_phases_list.schema.json';
+
+export async function handle(_input: unknown): Promise<ToolResponse> {
+  try {
+    const md = await readRoadmapMd(resolveProjectRoot());
+    return okResponse({ phases: parsePhases(md) });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-mcp/tools/gdd_plans_list.ts

@@ -0,0 +1,39 @@
+// scripts/mcp-servers/gdd-mcp/tools/gdd_plans_list.ts
+//
+// Plan 27.7-02. STATE.md does not have a dedicated <plans> block — we
+// surface must_haves as the closest analog (the per-plan acceptance
+// criteria the pipeline tracks). Input.phase is reserved for future
+// multi-phase indexing.
+
+import { read } from '../../../lib/gdd-state/index.ts';
+import {
+  errorResponse,
+  okResponse,
+  resolveStatePath,
+  type ToolResponse,
+} from './shared.ts';
+
+export const name = 'gdd_plans_list';
+export const schemaPath = '../schemas/gdd_plans_list.schema.json';
+
+interface PlansInput {
+  phase?: string;
+}
+
+export async function handle(input: unknown): Promise<ToolResponse> {
+  try {
+    const typed = (input ?? {}) as PlansInput;
+    const state = await read(resolveStatePath());
+    const plans = (state.must_haves ?? []).map((m) => ({
+      id: m.id,
+      name: m.text,
+      status: m.status,
+    }));
+    return okResponse({
+      phase: typed.phase ?? state.frontmatter.cycle ?? null,
+      plans,
+    });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-mcp/tools/gdd_reflections_latest.ts

@@ -0,0 +1,25 @@
+// scripts/mcp-servers/gdd-mcp/tools/gdd_reflections_latest.ts
+//
+// Plan 27.7-02. Reads newest reflection under .design/reflections/.
+// ReflectionsNotFoundError surfaces as mcp_code='directory_not_found'
+// via errorResponse (Warning #5).
+
+import { readLatestReflection } from '../../../lib/reflections-reader/index.cjs';
+import { errorResponse, okResponse, resolveProjectRoot, type ToolResponse } from './shared.ts';
+
+export const name = 'gdd_reflections_latest';
+export const schemaPath = '../schemas/gdd_reflections_latest.schema.json';
+
+export async function handle(_input: unknown): Promise<ToolResponse> {
+  try {
+    const r = await readLatestReflection(resolveProjectRoot());
+    if (r === null) return okResponse({ cycle: null, path: null, content_excerpt: '' });
+    return okResponse({
+      cycle: r.cycle,
+      path: r.path,
+      content_excerpt: r.content.slice(0, 4096),
+    });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}