@hegemonart/get-design-done 1.27.6 → 1.27.7

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.27.6"
+    "version": "1.27.7"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.27.6",
+      "version": "1.27.7",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.27.6",
-  "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
+  "version": "1.27.7",
+  "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming.",
   "author": {
     "name": "hegemonart",
     "url": "https://github.com/hegemonart"
@@ -59,7 +59,10 @@
     "gemini",
     "mcp",
     "parallel-agents",
-    "agent-sdk"
+    "agent-sdk",
+    "mcp-server",
+    "context-loading",
+    "cross-session"
   ],
   "skills": [
     "./skills/"

package/CHANGELOG.md

@@ -4,6 +4,55 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.27.7] — 2026-05-18
+
+### Added
+
+- **Phase 27.7 — GDD MCP Server** (7 plans). Ships `gdd-mcp`, a read-only Model Context Protocol server that exposes STATE.md sections, phases, decisions, plans, telemetry, intel slices, and the latest reflection as 12 typed MCP tools backed by the same `scripts/lib/*` modules the CLI uses. Sub-3-second priming target on a synthetic project (Storybloq §4.6 pattern transplant). Off-cadence v1.27.7 (CHANGELOG-only; mainline cadence resumes at v1.28.0).
+  - `scripts/mcp-servers/gdd-mcp/server.ts` (Plan 27.7-01) — MCP server scaffold using `@modelcontextprotocol/sdk` low-level Server + StdioServerTransport. Project-root discovery walks from `process.cwd()` looking for `.design/` OR `.planning/` OR `.claude-plugin/plugin.json`. `bin/gdd-mcp` shim added to `package.json` (alphabetized: gdd-events → gdd-mcp → gdd-sdk → gdd-state-mcp). Tests on handshake + walk-up + missing-marker behavior. (MCP-01)
+  - `scripts/mcp-servers/gdd-mcp/tools/` + `reference/schemas/mcp-gdd-tools.schema.json` (Plan 27.7-02) — 12 read-only tools: `gdd_status`, `gdd_cycle_recap`, `gdd_decisions_list`, `gdd_events_tail`, `gdd_health`, `gdd_intel_get`, `gdd_learnings_digest`, `gdd_phase_current`, `gdd_phases_list`, `gdd_plans_list`, `gdd_reflections_latest`, `gdd_telemetry_query`. Each tool ≤ 30 LOC (D-06), with per-tool Draft-07 JSON Schema, plus 5 helper libs (state-reader, intel-slicer, telemetry-grouper, reflection-loader, paths-resolver) and a `directory_not_found` typed projection. Tests on input schema + output shape + thin-wrapper assertion. (MCP-02)
+  - `scripts/lib/mcp-tools-lint/index.cjs` (Plan 27.7-03) — Static lint enforcing 4 invariants: forbid-fs-path (D-06: no direct `fs.*`/`path.*` in tool files), max-loc (≤ 30 LOC per tool), no-write-names (D-04: hard-blocks `_(create|update|delete|append|clear|write|set)` patterns), tool-count-cap (D-03: ≤ 12 files). Tests on each rule + exemptions for `index.ts`/`shared.ts`. (MCP-03)
+  - `scripts/lib/install/mcp-register.cjs` + `scripts/install.cjs --register-mcp` extension (Plan 27.7-04) — Idempotent registration with `claude mcp add` + `codex mcp add` (D-07 opt-in; absent-CLI fallback). `skills/health/SKILL.md` gains a `check-mcp-registration` step with 4 SKILL-row outputs (registered_with_both, not_registered, dismissed, unknown). Tests on idempotent re-run + absent-CLI paths + `--` arg-injection guard. (MCP-04)
+  - `skills/progress/SKILL.md` + `skills/resume/SKILL.md` + `skills/next/SKILL.md` adopted MCP-path + File-read-path fork (Plan 27.7-05). Each skill prefers `gdd-mcp` tools when registered, falls back to direct file reads when not. Structural-compliance tests via the Phase 28.5 validator. (MCP-05)
+  - `scripts/mcp-servers/gdd-mcp/README.md` (≤ 120 lines, Plan 27.7-06) + `test-fixture/baselines/phase-27-7/priming-benchmark.json` capturing −31.18% token reduction on a synthetic project (Storybloq's −30% floor met). Tests on README structure + benchmark fixture shape + token-reduction ≥ 30%. (MCP-06)
+  - `test-fixture/baselines/phase-27-7/` regression snapshots (Plan 27.7-07): `tool-registry.json` (12 tools, zero write-tools), `handshake-fixture.json` (canonical initialize response shape), `install-doctor-fixture.json` (4 SKILL-row scenarios), `manifests-version.txt` (pinned at 1.27.7). 4-manifest lockstep bump to v1.27.7. CHANGELOG entry. `OFF_CADENCE_VERSIONS.add('1.27.7')`. `reference/registry.json` gains `mcp-gdd-tools-schema` entry. `plugin.json` keywords gain `mcp-server`, `context-loading`, `cross-session`. ROADMAP scoped flip (7 plan checkboxes + 1 top-level overview entry). New `tests/phase-27-7-baseline.test.cjs` (>= 6 version-agnostic baseline tests) + new `tests/gdd-mcp-headless-e2e.test.cjs` (5 E2E tests: pack -> install -> spawn -> MCP initialize handshake -> tools/list returns 12; skip-on-Windows path documented for npm pack symlink false-negatives — Blocker #2 acceptance per ROADMAP SC #11). (MCP-07)
+
+### Decisions locked
+
+- D-01: MCP server is read-mostly (read-only in v1; mutations stay in slash-skills + lockfile-safe writers — re-examine at Phase 30/41).
+- D-02: Tool count capped at 12 — `TOOL_COUNT > 12` throws at module load. Adding a 13th tool requires re-scoping in a new plan.
+- D-03: 12-tool cap is the hard ceiling baselined in `test-fixture/baselines/phase-27-7/tool-registry.json`.
+- D-04: No write-verb tool names — `mcp-tools-lint` blocks `_(create|update|delete|append|clear|write|set)(_|$)` patterns. Baseline asserts `write_tools.length === 0`.
+- D-05: stdio-only transport — no port allocation, no HTTP surface. Project-root discovery walks up from `process.cwd()` (`.design/` OR `.planning/` OR `.claude-plugin/plugin.json` marker).
+- D-06: Each tool file ≤ 30 non-blank-non-comment LOC. Tools must be thin wrappers — no direct `node:fs`/`node:path` imports (enforced by `mcp-tools-lint`). All filesystem I/O routes through `scripts/lib/*` helpers.
+- D-07: Installer `--register-mcp` is opt-in (default off). Absent-CLI fallback emits a non-blocking notice. Dismissable nudge via `.design/config.json#mcp_nudge: false`.
+- D-08: Skill-side adoption is forked — MCP path (preferred) + File-read path (fallback). Both produce identical output shape. Skills do not hard-depend on MCP registration.
+- D-09: Server name `gdd-mcp` (matches package bin); version read from `package.json#version` (single source of truth — D-12 lockstep maintains alignment).
+- D-10: `bin/gdd-mcp` block in `package.json` alphabetized at scaffold time (Plan 27.7-01). Manifest bump preserves the alphabetization.
+- D-11: New schema `reference/schemas/mcp-gdd-tools.schema.json` registered in `reference/registry.json` as `mcp-gdd-tools-schema`.
+- D-12: 4-manifest lockstep — `package.json#version`, `.claude-plugin/plugin.json#version`, `.claude-plugin/marketplace.json#metadata.version`, `.claude-plugin/marketplace.json#plugins[0].version` all ship together at v1.27.7. `OFF_CADENCE_VERSIONS.add('1.27.7')` added to `tests/semver-compare.test.cjs`.
+
+### Tests added
+
+~69 new tests across 10 test files: 5 server scaffold (Plan 27.7-01), 27 tool + helper (Plan 27.7-02), 4 lint (Plan 27.7-03), 6 install + 4 SKILL row (Plan 27.7-04), 3 skill adoption (Plan 27.7-05), 5 README + benchmark (Plan 27.7-06), 8 baseline + 5 headless E2E (Plan 27.7-07).
+
+### Out of scope (deferred or rejected)
+
+- Write tools in v1 — `gdd_decision_append`, `gdd_blocker_clear`, `gdd_plan_complete` etc. Mutation belongs to slash-skills + lockfile-safe writers (Phase 20 surface), not callable-by-any-client MCP tools. Re-examine at Phase 30 (issue reporter) or Phase 41 (team mode).
+- Tool sprawl past 12 — Storybloq grew to 43 tools because read + write + autonomous + review-lens orchestration share the surface. GDD's autonomous surface is `/gdd:do`, review is `agents/*`. Re-examine when measured token-cost data justifies an additional tool.
+- Live (streaming) MCP resources — Phase 48 (`/gdd:live`) handles long-lived browser sessions via `channel/`-style subprocess registry; MCP stays request/response in v1.
+- Multi-project federation — one server, one project root. Two GDD projects in two terminals = two MCP servers. Federation is a Phase 41 (team mode) question.
+
+### Benchmark
+
+`test-fixture/baselines/phase-27-7/priming-benchmark.json` — synthetic-fixture priming run shows −31.18% token reduction (3 MCP calls vs equivalent file-reading path), with a 34× wall-clock speedup vs file-reading. Floor target was −30% (Storybloq's measured number); GDD exceeds the floor. Real-cycle calibration follows in a patch after 1-2 production cycles.
+
+### Headless E2E (ROADMAP SC #11)
+
+`tests/gdd-mcp-headless-e2e.test.cjs` — `npm pack` produces tarball -> `npm install <tarball>` into mkdtempSync prefix -> spawn `gdd-mcp` via the installed bin -> MCP initialize handshake asserts `serverInfo.name === 'gdd-mcp'` + `serverInfo.version === package.json#version` -> follow-up `tools/list` asserts `result.tools.length === 12`. Cleanup at end. Marked `skip: process.platform === 'win32'` for npm pack symlink false-negatives (Blocker #2 acceptance); POSIX CI runs all 5 E2E tests.
+
+---
+
 ## [1.27.6] — 2026-05-18
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.27.6",
+  "version": "1.27.7",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -27,10 +27,11 @@
     "LICENSE"
   ],
   "bin": {
-    "get-design-done": "./scripts/install.cjs",
-    "gdd-state-mcp": "./scripts/mcp-servers/gdd-state/server.ts",
+    "gdd-events": "./scripts/cli/gdd-events.mjs",
+    "gdd-mcp": "./scripts/mcp-servers/gdd-mcp/server.ts",
     "gdd-sdk": "./bin/gdd-sdk",
-    "gdd-events": "./scripts/cli/gdd-events.mjs"
+    "gdd-state-mcp": "./scripts/mcp-servers/gdd-state/server.ts",
+    "get-design-done": "./scripts/install.cjs"
   },
   "publishConfig": {
     "access": "public",

package/reference/registry.json

@@ -455,6 +455,13 @@
       "type": "defaults",
       "description": "Default MCP per-task budget (calls + consecutive-timeout thresholds)"
     },
+    {
+      "name": "mcp-gdd-tools-schema",
+      "path": "reference/schemas/mcp-gdd-tools.schema.json",
+      "type": "schema",
+      "phase": 27.7,
+      "description": "Phase 27.7 — Draft-07 input/output schemas for the 12 read-only tools in scripts/mcp-servers/gdd-mcp/ (gdd-mcp MCP server)"
+    },
     {
       "name": "meta-rules",
       "path": "reference/meta-rules.md",

package/reference/schemas/mcp-gdd-tools.schema.json

@@ -0,0 +1,381 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/hegemonart/get-design-done/main/reference/schemas/mcp-gdd-tools.schema.json",
+  "title": "McpGddTools",
+  "description": "Combined manifest of all gdd-mcp tool input+output schemas (Plan 27.7-02). Individual tool schemas live under scripts/mcp-servers/gdd-mcp/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface (D-11).",
+  "type": "object",
+  "properties": {
+    "tools": {
+      "type": "object",
+      "description": "Per-tool input/output schemas keyed by tool name. Exactly 12 entries (D-03 hard cap).",
+      "additionalProperties": false,
+      "properties": {
+        "gdd_status": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "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 }
+              }
+            }
+          }
+        },
+        "gdd_phase_current": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "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"] }
+              }
+            }
+          }
+        },
+        "gdd_phases_list": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "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"] }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "gdd_plans_list": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "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" }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "gdd_decisions_list": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "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" }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "gdd_intel_get": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "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" }
+              }
+            }
+          }
+        },
+        "gdd_telemetry_query": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "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" } }
+              }
+            }
+          }
+        },
+        "gdd_cycle_recap": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "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" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "gdd_reflections_latest": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "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 }
+              }
+            }
+          }
+        },
+        "gdd_learnings_digest": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "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 }
+              }
+            }
+          }
+        },
+        "gdd_events_tail": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "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" } }
+              }
+            }
+          }
+        },
+        "gdd_health": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "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" }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "ToolSchemaEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["input", "output"],
+      "properties": {
+        "input": {
+          "type": "object",
+          "description": "JSON Schema fragment describing the tool's input parameters."
+        },
+        "output": {
+          "type": "object",
+          "description": "JSON Schema fragment describing the tool's response envelope.",
+          "required": ["type"],
+          "properties": {
+            "type": { "type": "string", "enum": ["object"] }
+          }
+        }
+      }
+    },
+    "ToolError": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message", "kind"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "kind": {
+          "type": "string",
+          "enum": ["validation", "state_conflict", "operation_failed", "unknown"]
+        },
+        "mcp_code": {
+          "type": "string",
+          "description": "Optional MCP-specific code (e.g. 'directory_not_found') projected by errorResponse() when an underlying NotFoundError carries a `code` property."
+        },
+        "context": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    },
+    "ToolResponseEnvelope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["success"],
+      "properties": {
+        "success": { "type": "boolean" },
+        "data": { "type": "object" },
+        "error": { "$ref": "#/definitions/ToolError" }
+      }
+    }
+  }
+}

package/scripts/install.cjs

@@ -62,6 +62,8 @@ function helpText() {
     '  --dry-run       Print the diff without writing',
     '  --config-dir D  Override the config directory',
     '  --no-peer-prompt  Suppress the post-install peer-CLI detection nudge',
+    '  --register-mcp     Register gdd-mcp with detected harnesses (Claude Code, Codex). Opt-in.',
+    '  --no-register-mcp  Skip MCP registration (default behavior; included for symmetry).',
     '  --help, -h      Show this message',
     '',
     'Environment overrides (per-runtime):',
@@ -215,6 +217,46 @@ async function main() {
       );
     }
   }
+
+  // Phase 27.7 / Plan 27.7-04 — opt-in MCP registration (D-07).
+  // Fires only on real install (not uninstall, not dry-run) when the user
+  // passes --register-mcp explicitly. Default OFF; --no-register-mcp is a
+  // no-op today (reserved for symmetry / when default flips). Idempotent
+  // + graceful absent-CLI fallback handled inside registerMcp.
+  if (!uninstall && !dryRun && flags.has('--register-mcp')) {
+    try {
+      const { registerMcp } = require('./lib/install/mcp-register.cjs');
+      for (const harness of ['claude', 'codex']) {
+        try {
+          const result = registerMcp({ harness });
+          if (!result.detected) {
+            process.stderr.write('[install] ' + result.notice + '\n');
+          } else if (result.idempotent_skip) {
+            process.stdout.write(
+              '[install] gdd-mcp already registered with ' + harness + ' — skipping.\n',
+            );
+          } else if (result.applied) {
+            process.stdout.write(
+              '[install] gdd-mcp registered with ' + harness + '.\n',
+            );
+          } else {
+            process.stderr.write(
+              '[install] gdd-mcp registration with ' + harness + ' failed: exit ' + result.exit_code + '\n',
+            );
+          }
+        } catch (err) {
+          process.stderr.write(
+            '[install] gdd-mcp registration error (' + harness + '): ' + (err && err.message ? err.message : err) + '\n',
+          );
+        }
+      }
+    } catch (e) {
+      // mcp-register lib not present (forward-compat) — silent skip.
+      process.stderr.write(
+        '[install] mcp-register lib unavailable: ' + (e && e.message ? e.message : e) + '\n',
+      );
+    }
+  }
 }
 
 // v1.27.1 — Plan 27-11: post-install nudge. Detects installed peer CLIs,