@hegemonart/get-design-done 1.27.6 → 1.28.0

package/scripts/lib/reflections-reader/index.cjs

@@ -0,0 +1,107 @@
+'use strict';
+// scripts/lib/reflections-reader/index.cjs — Plan 27.7-02
+//
+// Read post-cycle reflections from <rootDir>/.design/reflections/.
+//
+// Surface:
+//   class ReflectionsNotFoundError extends Error  — code='directory_not_found'
+//   async readLatestReflection(rootDir)           — { cycle, path, content } | null
+//   async readNReflections(rootDir, n)            — same shape, sorted desc by mtime
+//   digestReflections(reflections)                — string, <= 5120 chars
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DIGEST_CAP_BYTES = 5120;
+
+class ReflectionsNotFoundError extends Error {
+  constructor(dir) {
+    super('source directory not found: ' + dir);
+    this.name = 'ReflectionsNotFoundError';
+    this.code = 'directory_not_found';
+    this.dir = dir;
+  }
+}
+
+async function listReflectionFiles(dir) {
+  const entries = await fs.promises.readdir(dir);
+  const candidates = [];
+  for (const name of entries) {
+    if (!name.endsWith('.md')) continue;
+    const full = path.join(dir, name);
+    try {
+      const stat = await fs.promises.stat(full);
+      candidates.push({ name, full, mtime: stat.mtimeMs });
+    } catch {
+      // ignore — race with concurrent write
+    }
+  }
+  candidates.sort((a, b) => b.mtime - a.mtime);
+  return candidates;
+}
+
+/** Extract a cycle id from a reflection filename. Convention: filenames
+ *  like `2026-05-17-cycle27.7.md` or `cycle-NN.md`; we pick the first
+ *  `cycle*` token, falling back to the basename. */
+function extractCycle(name) {
+  const m = name.match(/cycle[-_]?[\w.]+/i);
+  if (m) return m[0];
+  return name.replace(/\.md$/, '');
+}
+
+async function readLatestReflection(rootDir) {
+  const dir = path.join(rootDir, '.design', 'reflections');
+  if (!fs.existsSync(dir)) {
+    throw new ReflectionsNotFoundError(dir);
+  }
+  const files = await listReflectionFiles(dir);
+  if (files.length === 0) return null;
+  const f = files[0];
+  const content = await fs.promises.readFile(f.full, 'utf8');
+  return { cycle: extractCycle(f.name), path: f.full, content };
+}
+
+async function readNReflections(rootDir, n) {
+  const dir = path.join(rootDir, '.design', 'reflections');
+  if (!fs.existsSync(dir)) {
+    throw new ReflectionsNotFoundError(dir);
+  }
+  const files = await listReflectionFiles(dir);
+  const take = Math.max(0, Math.min(n, files.length));
+  const out = [];
+  for (let i = 0; i < take; i++) {
+    const f = files[i];
+    const content = await fs.promises.readFile(f.full, 'utf8');
+    out.push({ cycle: extractCycle(f.name), path: f.full, content });
+  }
+  return out;
+}
+
+/** Aggregate reflections into a compact digest <= 5 KB. Strategy: take
+ *  the first 300 chars of each reflection's body (skipping any leading
+ *  frontmatter `---` block); join with `\n---\n`; truncate at the cap. */
+function digestReflections(reflections) {
+  const parts = [];
+  for (const r of reflections) {
+    let body = r.content;
+    // Strip leading YAML frontmatter if present
+    if (body.startsWith('---')) {
+      const closing = body.indexOf('\n---', 3);
+      if (closing !== -1) body = body.slice(closing + 4).trim();
+    }
+    const excerpt = body.slice(0, 300).trim();
+    parts.push('[' + r.cycle + '] ' + excerpt);
+  }
+  let joined = parts.join('\n---\n');
+  if (joined.length > DIGEST_CAP_BYTES) {
+    joined = joined.slice(0, DIGEST_CAP_BYTES);
+  }
+  return joined;
+}
+
+module.exports = {
+  readLatestReflection,
+  readNReflections,
+  digestReflections,
+  ReflectionsNotFoundError,
+};

package/scripts/lib/reflections-reader/index.d.cts

@@ -0,0 +1,18 @@
+// scripts/lib/reflections-reader/index.d.cts — TypeScript ambient declarations
+// for the reflections-reader CJS module. Plan 27.7-02.
+
+export class ReflectionsNotFoundError extends Error {
+  code: 'directory_not_found';
+  dir: string;
+  constructor(dir: string);
+}
+
+export interface Reflection {
+  cycle: string;
+  path: string;
+  content: string;
+}
+
+export function readLatestReflection(rootDir: string): Promise<Reflection | null>;
+export function readNReflections(rootDir: string, n: number): Promise<Reflection[]>;
+export function digestReflections(reflections: Reflection[]): string;

package/scripts/lib/roadmap-reader/index.cjs

@@ -0,0 +1,81 @@
+'use strict';
+// scripts/lib/roadmap-reader/index.cjs — Plan 27.7-02
+//
+// Read + parse .planning/ROADMAP.md into a flat list of phase entries
+// consumed by the gdd_phases_list MCP tool. Pure read; no I/O outside
+// readRoadmapMd().
+//
+// Output shape per phase:
+//   { number: '27.7', name: 'GDD MCP Server', version: 'v1.27.7',
+//     checkbox_status: 'shipped' | 'planned' | 'unknown' }
+//
+// `checkbox_status` is sourced from the overview list at the top of
+// ROADMAP.md (lines shaped `- [x] [Phase 27]...` or `- [ ] [Phase 27.7]...`).
+// When no overview line matches the heading, we emit `'unknown'`.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** Read .planning/ROADMAP.md from rootDir; returns full markdown string. */
+async function readRoadmapMd(rootDir) {
+  const p = path.join(rootDir, '.planning', 'ROADMAP.md');
+  return fs.promises.readFile(p, 'utf8');
+}
+
+/**
+ * Parse the body of ROADMAP.md into phase entries. Two passes:
+ *   1. Scan `- [x|space] [Phase <num>](...)` overview lines → status map
+ *   2. Scan `### Phase <num>: <name>` headings → main list
+ *
+ * The version is pulled from the FIRST line after the heading that
+ * matches `**Target version**:` or `— v\S+`. We tolerate trailing
+ * parenthetical commentary on the heading by trimming everything after
+ * a trailing ` (…)` chunk.
+ */
+function parsePhases(md) {
+  // Pass 1 — overview checkbox map. Pattern matches both `Phase 27` and
+  // `Phase 27.7`; ignores the descriptive name + version that may follow.
+  const statusMap = new Map();
+  const overviewRe = /^-\s+\[([x\s])\]\s+\[Phase\s+(\S+?)\]/gm;
+  let mm;
+  while ((mm = overviewRe.exec(md)) !== null) {
+    const checked = mm[1] === 'x';
+    statusMap.set(mm[2], checked ? 'shipped' : 'planned');
+  }
+
+  // Pass 2 — Phase heading scan. We capture the number + name, then
+  // look ahead in the heading's section for a version marker. The
+  // heading may have an embedded version (` — v1.X.Y`) or rely on
+  // a `**Target version**:` block below.
+  const headingRe = /^###\s+Phase\s+(\S+?):\s+([^\n]+?)$/gm;
+  const phases = [];
+  let h;
+  while ((h = headingRe.exec(md)) !== null) {
+    const number = h[1];
+    let name = h[2].trim();
+    // Strip trailing parenthetical commentary (e.g. `(INSERTED)`).
+    name = name.replace(/\s+\([^)]*\)\s*$/g, '').trim();
+    // Strip trailing version chunk from the heading itself.
+    const inlineVer = name.match(/\s+—\s+(v\d+\.\d+(?:\.\d+)?)/);
+    let version = inlineVer ? inlineVer[1] : '';
+    if (inlineVer) {
+      name = name.slice(0, inlineVer.index).trim();
+    }
+    // If no inline version, look forward in the next ~30 lines for a
+    // `**Target version**:` block.
+    if (version === '') {
+      const after = md.slice(h.index, h.index + 2000);
+      const v = after.match(/\*\*Target version\*\*:\s*(v\d+\.\d+(?:\.\d+)?)/);
+      if (v) version = v[1];
+    }
+    phases.push({
+      number,
+      name,
+      version,
+      checkbox_status: statusMap.get(number) ?? 'unknown',
+    });
+  }
+  return phases;
+}
+
+module.exports = { readRoadmapMd, parsePhases };

package/scripts/lib/roadmap-reader/index.d.cts

@@ -0,0 +1,13 @@
+// scripts/lib/roadmap-reader/index.d.cts — TypeScript ambient declarations
+// for the roadmap-reader CJS module. Plan 27.7-02 — TS imports of CJS
+// need .d.cts siblings (Phase 27.6 lesson).
+
+export interface ParsedPhase {
+  number: string;
+  name: string;
+  version: string;
+  checkbox_status: 'shipped' | 'planned' | 'unknown';
+}
+
+export function readRoadmapMd(rootDir: string): Promise<string>;
+export function parsePhases(md: string): ParsedPhase[];

package/scripts/lib/snapshot-reader/index.cjs

@@ -0,0 +1,70 @@
+'use strict';
+// scripts/lib/snapshot-reader/index.cjs — Plan 27.7-02
+//
+// Read latest snapshot under .design/snapshots/ (written by
+// hooks/gdd-precompact-snapshot.js; see Phase 27.6 Plan 05).
+//
+// Surface:
+//   class SnapshotNotFoundError extends Error  — code='directory_not_found'
+//   async readLatestSnapshot(rootDir)          — { since, snapshot } | null
+//
+// `since` is the snapshot's embedded `timestamp` (ISO 8601), falling
+// back to the file's mtime if absent.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+class SnapshotNotFoundError extends Error {
+  constructor(dir) {
+    super('source directory not found: ' + dir);
+    this.name = 'SnapshotNotFoundError';
+    this.code = 'directory_not_found';
+    this.dir = dir;
+  }
+}
+
+/**
+ * Read the newest *.json file under <rootDir>/.design/snapshots/.
+ * Returns `{ since, snapshot }` or `null` when the directory exists
+ * but contains no snapshot files. Throws SnapshotNotFoundError when
+ * the directory itself is missing.
+ */
+async function readLatestSnapshot(rootDir) {
+  const dir = path.join(rootDir, '.design', 'snapshots');
+  if (!fs.existsSync(dir)) {
+    throw new SnapshotNotFoundError(dir);
+  }
+  const entries = await fs.promises.readdir(dir);
+  const candidates = [];
+  for (const name of entries) {
+    if (!name.endsWith('.json')) continue;
+    if (name === 'last-recap.json') continue;
+    const full = path.join(dir, name);
+    try {
+      const stat = await fs.promises.stat(full);
+      candidates.push({ full, mtime: stat.mtimeMs });
+    } catch {
+      // ignore — race with retention prune
+    }
+  }
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => b.mtime - a.mtime);
+  const winner = candidates[0];
+  const body = await fs.promises.readFile(winner.full, 'utf8');
+  let snapshot;
+  try {
+    snapshot = JSON.parse(body);
+  } catch (err) {
+    // Malformed snapshot — surface a parseable error
+    throw new Error(
+      'snapshot parse failed: ' + winner.full + ': ' + (err && err.message ? err.message : String(err)),
+    );
+  }
+  const since =
+    typeof snapshot.timestamp === 'string' && snapshot.timestamp.length > 0
+      ? snapshot.timestamp
+      : new Date(winner.mtime).toISOString();
+  return { since, snapshot };
+}
+
+module.exports = { readLatestSnapshot, SnapshotNotFoundError };

package/scripts/lib/snapshot-reader/index.d.cts

@@ -0,0 +1,28 @@
+// scripts/lib/snapshot-reader/index.d.cts — TypeScript ambient declarations
+// for the snapshot-reader CJS module. Plan 27.7-02.
+
+export class SnapshotNotFoundError extends Error {
+  code: 'directory_not_found';
+  dir: string;
+  constructor(dir: string);
+}
+
+export interface SnapshotPayload {
+  /** Snapshot body — shape is JSON-loose; consumers project keys. */
+  schema_version?: string;
+  timestamp?: string;
+  cycle_id?: string;
+  state_md_sections?: unknown;
+  last_n_events?: unknown[];
+  last_n_decisions?: unknown[];
+  decisions_count?: number;
+  completed_plans_count?: number;
+  [k: string]: unknown;
+}
+
+export interface ReadSnapshotResult {
+  since: string;
+  snapshot: SnapshotPayload;
+}
+
+export function readLatestSnapshot(rootDir: string): Promise<ReadSnapshotResult | null>;

package/scripts/mcp-servers/gdd-mcp/README.md

@@ -0,0 +1,66 @@
+# gdd-mcp
+
+Read-only MCP server exposing GDD project state — STATE.md sections, phases, decisions, plans, telemetry, intel slices, latest reflections — as 12 typed MCP tools. Sessions prime in 3 MCP calls instead of 100+ file reads, on the same project a per-session reduction of −30% tokens and ~34× wall-clock speedup (see benchmark below).
+
+Phase 27.7. Mirror of the `scripts/mcp-servers/gdd-state/` Phase 20 pattern. v1 is read-only — mutation belongs to slash-skills and the lockfile-safe `gdd-state-mcp` writers (Phase 20 surface).
+
+## Tools
+
+| Name | Input | Output (one-line summary) |
+|------|-------|---------------------------|
+| `gdd_status` | `{}` | Current cycle phase, branch, last-3 decisions, last-3 completed plans, blocker count |
+| `gdd_phase_current` | `{}` | Current phase + stage + task_progress + status from STATE.md `<position>` |
+| `gdd_phases_list` | `{}` | Phases from ROADMAP.md overview parse |
+| `gdd_plans_list` | `{phase?}` | Plans for the current (or specified) phase from STATE.md `<plans>` |
+| `gdd_decisions_list` | `{status?}` | D-XX decisions from STATE.md `<decisions>`, optionally filtered |
+| `gdd_intel_get` | `{slice_id, shape?}` | Slice query against `.design/intel/` with optional key projection |
+| `gdd_telemetry_query` | `{type?, since?, limit?}` | Typed reader over `.design/telemetry/*.jsonl` |
+| `gdd_cycle_recap` | `{since_snapshot?}` | Diff vs the last Phase 27.6 snapshot (STATE sections + decisions + plans) |
+| `gdd_reflections_latest` | `{}` | Latest cycle reflection excerpt from `.design/reflections/` (≤4 KB) |
+| `gdd_learnings_digest` | `{cycles?}` | Compact lessons digest of recent reflections (≤5 KB) |
+| `gdd_events_tail` | `{type?, limit?}` | Last N events from event-chain with optional type filter |
+| `gdd_health` | `{}` | Read-only mirror of `skills/health/SKILL.md` checks payload |
+
+All tools are thin wrappers (≤30 LOC) over `scripts/lib/*` helpers. The lint rule at `scripts/lib/mcp-tools-lint/` enforces no direct `fs.*`/`path.*` imports and zero write-tool names (`_create`, `_update`, `_delete`, `_append`, `_clear`, `_write`, `_set`). The 12-tool cap is hard (D-03) — adding a 13th requires a new plan.
+
+Schemas live under `reference/schemas/mcp-gdd-tools.schema.json` (Draft-07). Tool sources are under `scripts/mcp-servers/gdd-mcp/tools/*.ts`.
+
+## Manual registration
+
+```bash
+# Opt-in via installer (idempotent, detects Claude Code + Codex CLIs):
+npx @hegemonart/get-design-done --register-mcp
+
+# Or manual (Claude Code):
+claude mcp add gdd-mcp -s user -- gdd-mcp
+
+# Or manual (Codex):
+codex mcp add gdd-mcp -- gdd-mcp
+```
+
+Dismiss the gdd-health MCP-registration nudge by setting `.design/config.json` to `{"mcp_nudge": false}`.
+
+## When to prefer MCP vs file reads
+
+| Scenario | Use MCP | Use file reads |
+|----------|---------|----------------|
+| Cold-boot priming (`/gdd:progress`, `/gdd:resume`, `/gdd:next`) | Yes — 3 calls, ~3 s, ~32k tokens | Fallback only when MCP unavailable |
+| Mid-cycle context refresh in stage skills | Yes — 1–2 targeted calls | Fallback only |
+| Editing STATE.md sections | No — use `mcp__gdd_state__*` (Phase 20) | N/A |
+| Listing all skills | No — slash-skills + `scripts/list-skills.cjs` | N/A |
+| Reading arbitrary untracked files | No | Yes — Read tool |
+
+**Benchmark** (synthetic fixture at `test-fixture/baselines/phase-27-7/priming-benchmark.json`, modeled on Storybloq v1.2.0 measured numbers):
+
+- MCP path: 3 calls, ~3 s, ~32k tokens
+- File-read path: 5–10 reads, ~101 s, ~46.5k tokens
+- Reduction: −31% tokens, ~34× wall-clock speedup
+
+Per CONTEXT.md D-09 the benchmark is informational — failure to hit the −30% target surfaces as a Phase 27.7 success-criterion regression in closeout (Plan 27.7-07), NOT a CI hard-fail. After 5–10 real cycles, the synthetic fixture is replaced with measured GDD numbers (research-tail item).
+
+## See also
+
+- `scripts/mcp-servers/gdd-state/` — Phase 20 STATE.md mutation MCP (write surface)
+- `scripts/lib/mcp-tools-lint/` — Static analysis enforcing thin-wrapper discipline
+- `reference/schemas/mcp-gdd-tools.schema.json` — Tool input/output schemas (Draft-07)
+- `.planning/phases/27.7-gdd-mcp-server/CONTEXT.md` — Phase 27.7 decisions and rationale

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

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gdd_cycle_recap",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "since_snapshot": { "type": "string" }
+      }
+    },
+    "output": {
+      "type": "object",
+      "required": ["since", "diff"],
+      "properties": {
+        "since": { "type": ["string", "null"] },
+        "diff": {
+          "type": "object",
+          "required": ["state_sections", "decisions_delta", "completed_plans_delta"],
+          "properties": {
+            "state_sections": { "type": "array", "items": { "type": "string" } },
+            "decisions_delta": { "type": "integer" },
+            "completed_plans_delta": { "type": "integer" }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gdd_decisions_list",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "status": { "type": "string", "enum": ["locked", "tentative"] }
+      }
+    },
+    "output": {
+      "type": "object",
+      "required": ["decisions"],
+      "properties": {
+        "decisions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "text", "status"],
+            "properties": {
+              "id": { "type": "string" },
+              "text": { "type": "string" },
+              "status": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gdd_events_tail",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string" },
+        "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/schemas/gdd_health.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gdd_health",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {}
+    },
+    "output": {
+      "type": "object",
+      "required": ["checks"],
+      "properties": {
+        "checks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "status", "detail"],
+            "properties": {
+              "name": { "type": "string" },
+              "status": { "type": "string", "enum": ["ok", "warn", "fail"] },
+              "detail": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gdd_intel_get",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slice_id"],
+      "properties": {
+        "slice_id": { "type": "string", "minLength": 1 },
+        "shape": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "output": {
+      "type": "object",
+      "required": ["slice_id", "data"],
+      "properties": {
+        "slice_id": { "type": "string" },
+        "data": { "type": "object" }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gdd_learnings_digest",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "cycles": { "type": "integer", "minimum": 1, "maximum": 50 }
+      }
+    },
+    "output": {
+      "type": "object",
+      "required": ["digest", "cycles_included"],
+      "properties": {
+        "digest": { "type": "string", "maxLength": 5120 },
+        "cycles_included": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gdd_phase_current",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {}
+    },
+    "output": {
+      "type": "object",
+      "required": ["phase", "stage", "task_progress", "status"],
+      "properties": {
+        "phase": { "type": ["string", "null"] },
+        "stage": { "type": ["string", "null"] },
+        "task_progress": { "type": ["string", "null"] },
+        "status": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gdd_phases_list",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {}
+    },
+    "output": {
+      "type": "object",
+      "required": ["phases"],
+      "properties": {
+        "phases": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["number", "name", "version", "checkbox_status"],
+            "properties": {
+              "number": { "type": "string" },
+              "name": { "type": "string" },
+              "version": { "type": "string" },
+              "checkbox_status": { "type": "string", "enum": ["shipped", "planned", "unknown"] }
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gdd_plans_list",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "phase": { "type": "string" }
+      }
+    },
+    "output": {
+      "type": "object",
+      "required": ["phase", "plans"],
+      "properties": {
+        "phase": { "type": ["string", "null"] },
+        "plans": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "name", "status"],
+            "properties": {
+              "id": { "type": "string" },
+              "name": { "type": "string" },
+              "status": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gdd_reflections_latest",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {}
+    },
+    "output": {
+      "type": "object",
+      "required": ["cycle", "path", "content_excerpt"],
+      "properties": {
+        "cycle": { "type": ["string", "null"] },
+        "path": { "type": ["string", "null"] },
+        "content_excerpt": { "type": "string", "maxLength": 4096 }
+      }
+    }
+  }
+}