@hegemonart/get-design-done 1.58.1 → 1.59.1

package/.claude-plugin/marketplace.json

@@ -4,15 +4,15 @@
     "name": "hegemonart"
   },
   "metadata": {
-    "description": "Get Design Done — 5-stage agent-orchestrated design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 agents, 94 skills, 42 connection integrations, two MCP servers, opt-in SQLite state backbone, bidirectional Figma write-back, and a reflector-driven self-improvement loop. Cross-runtime install for Claude Code, Codex, Cursor, OpenCode, Gemini, and more.",
-    "version": "1.58.1"
+    "description": "Get Design Done — 5-stage agent-orchestrated design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 agents, 95 skills, 42 connection integrations, two MCP servers, opt-in SQLite state backbone, bidirectional Figma write-back, and a reflector-driven self-improvement loop. Cross-runtime install for Claude Code, Codex, Cursor, OpenCode, Gemini, and more.",
+    "version": "1.59.1"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
-      "description": "Agent-orchestrated 5-stage design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 specialized agents, 94 skills, 42 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Linear, Jira, Notion, …), bidirectional Figma write-back, queryable intel store, opt-in SQLite state backbone, and a reflector-driven self-improvement loop. Two MCP servers (gdd-state for typed STATE mutators, gdd-mcp for 13 read-only project-priming tools), tier-aware routing with cost telemetry, and defense-in-depth hooks (protected paths, MCP circuit breaker, injection scanner, budget enforcer). Cross-runtime install for Claude Code, Codex, Cursor, OpenCode, Gemini, Copilot, and more.",
-      "version": "1.58.1",
+      "description": "Agent-orchestrated 5-stage design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 specialized agents, 95 skills, 42 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Linear, Jira, Notion, …), bidirectional Figma write-back, queryable intel store, opt-in SQLite state backbone, and a reflector-driven self-improvement loop. Two MCP servers (gdd-state for typed STATE mutators, gdd-mcp for 13 read-only project-priming tools), tier-aware routing with cost telemetry, and defense-in-depth hooks (protected paths, MCP circuit breaker, injection scanner, budget enforcer). Cross-runtime install for Claude Code, Codex, Cursor, OpenCode, Gemini, Copilot, and more.",
+      "version": "1.59.1",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.58.1",
-  "description": "Agent-orchestrated 5-stage design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 specialized agents, 94 skills, 42 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Linear, Jira, Notion, …), bidirectional Figma write-back, queryable intel store for O(1) design-surface lookups, opt-in SQLite state backbone, and a reflector-driven self-improvement loop. Two MCP servers (`gdd-state` for typed STATE mutators, `gdd-mcp` for 13 read-only project-priming tools), tier-aware agent routing with cost telemetry, defense-in-depth hooks (protected paths, MCP circuit breaker, injection scanner, budget enforcer), and a cross-runtime install layer for Claude Code, Codex, Cursor, OpenCode, Gemini, Copilot, and more.",
+  "version": "1.59.1",
+  "description": "Agent-orchestrated 5-stage design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 specialized agents, 95 skills, 42 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Linear, Jira, Notion, …), bidirectional Figma write-back, queryable intel store for O(1) design-surface lookups, opt-in SQLite state backbone, and a reflector-driven self-improvement loop. Two MCP servers (`gdd-state` for typed STATE mutators, `gdd-mcp` for 13 read-only project-priming tools), tier-aware agent routing with cost telemetry, defense-in-depth hooks (protected paths, MCP circuit breaker, injection scanner, budget enforcer), and a cross-runtime install layer for Claude Code, Codex, Cursor, OpenCode, Gemini, Copilot, and more.",
   "author": {
     "name": "hegemonart",
     "url": "https://github.com/hegemonart"
@@ -56,5 +56,19 @@
   ],
   "skills": [
     "./skills/"
-  ]
+  ],
+  "mcpServers": {
+    "gdd-mcp": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/bin/gdd-mcp"
+      ]
+    },
+    "gdd-state": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/bin/gdd-state-mcp"
+      ]
+    }
+  }
 }

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.59.1] - 2026-06-04
+
+First point release of the **v1.59 "Audit Closeout & Honesty Pass"** milestone. The two bundled MCP servers now come up for users automatically, plus the cheapest correctness/honesty fixes.
+
+### MCP servers register automatically on Claude Code
+
+The two bundled MCP servers - `gdd-state` (typed STATE mutators) and `gdd-mcp` (read-only project-priming tools) - are now declared under `mcpServers` in `.claude-plugin/plugin.json`, so a fresh Claude Code marketplace install exposes both servers' tools with no manual `--register-mcp` step. They launch through the plugin-local `bin/` trampolines via `${CLAUDE_PLUGIN_ROOT}`, so the git-clone install path works without `npm install`.
+
+### Added
+
+- **`/gdd:bandit-reset`** - a confirm-then-reset maintenance skill for the bandit posterior (`.design/telemetry/posterior.json`): backs the file up to `posterior.json.bak`, then clears it to a fresh envelope. The mutation companion to the read-only `/gdd:bandit-status`. Resolves the previously-dangling `/gdd:bandit-reset` reference. (Skill count 94 → 95.)
+
+### Fixed
+
+- **Installer parity** - `get-design-done --register-mcp` now registers BOTH `gdd-mcp` and `gdd-state` for Claude Code and Codex (previously `gdd-mcp` only). `--no-register-mcp` is unchanged.
+- **MCP launch warning** - the servers no longer print a `MODULE_TYPELESS_PACKAGE_JSON` warning on startup (suppressed in the dev/source launch path; the compiled npm-install path is unaffected).
+- **`gdd-sdk audit`** now degrades gracefully with no active cycle (no `.design/STATE.md`): it prints a "no active cycle" notice, runs the static checks, and exits 0 instead of throwing.
+- **Dead path references** - repointed stale `scripts/mcp-servers/...` and `scripts/lib/{gdd-state,event-stream,gdd-errors}/...` references (relocated to `sdk/...` in v1.33.0) to their live locations, including a broken `claude mcp add` command in the `gdd-state` connection doc.
+
+### Changed
+
+- Removed two dead npm scripts (`typecheck:session-runner`, `validate:skill-surface`) and pointed the `gdd-sdk` script at the Windows-safe `bin/gdd-sdk` trampoline.
+- Regenerated `reference/schemas/generated.d.ts` from source schemas.
+
+### Breaking changes
+
+None.
+
+5,013/5,013 tests pass.
+
+---
+
 ## [1.58.1] - 2026-06-04
 
 ### Hotfix - restore committed skills/ for Claude Code marketplace install
@@ -1828,7 +1860,7 @@ The `gsd-build/get-shit-done` rug-pull in May 2026 (TÂCHES drained $GSD Solana
 - **`.design/graph/`** replaces upstream's `.planning/graphs/` location (per D-02 - aligns with the rest of GDD's `.design/` artifact convention).
 - **`connections/graphify.md`** rewritten for native CLI (no external `graphifyy` dependency).
 - **`reference/start-interview.md`** updated to reference `/gdd:discuss` (our equivalent) instead of `/gsd-discuss-phase`.
-- **`README.md`** at the `gsd-build/get-shit-done (MIT — see NOTICE)` citation gains the redux-pointer parenthetical "(now archived; community continuation at `open-gsd/get-shit-done-redux`)". Citation preserved verbatim - only annotated for reader clarity.
+- **`README.md`** at the `gsd-build/get-shit-done (MIT - see NOTICE)` citation gains the redux-pointer parenthetical "(now archived; community continuation at `open-gsd/get-shit-done-redux`)". Citation preserved verbatim - only annotated for reader clarity.
 - **Graphify enable/disable state** (D-09) lives in `.design/config.json` at `{ "graphify": { "enabled": bool } }`. Read directly by `gdd-graph` via fs; no `config-set` / `config-get` CLI subcommand.
 
 ### Removed
@@ -1858,7 +1890,7 @@ The `gsd-build/get-shit-done` rug-pull in May 2026 (TÂCHES drained $GSD Solana
 
 ### Attribution preservation
 
-Phase 27 / Phase 28.5 / Phase 28.7 attribution subsections in `NOTICE` are preserved verbatim per D-06. The architectural ports they describe are historical MIT-licensed code transplants; this release removes a runtime touchpoint, **NOT** a historical port. The `gsd-build/get-shit-done (MIT — see NOTICE)` citation in `README.md` is preserved verbatim; only the redux-pointer parenthetical was added.
+Phase 27 / Phase 28.5 / Phase 28.7 attribution subsections in `NOTICE` are preserved verbatim per D-06. The architectural ports they describe are historical MIT-licensed code transplants; this release removes a runtime touchpoint, **NOT** a historical port. The `gsd-build/get-shit-done (MIT - see NOTICE)` citation in `README.md` is preserved verbatim; only the redux-pointer parenthetical was added.
 
 ---
 
@@ -1880,7 +1912,7 @@ Decimal sub-phase building on Phase 30's `/gdd:report-issue` triage gate. Expand
 ### Changed
 
 - **Reflector capability-gap aggregator** (`scripts/lib/reflector-capability-gap-aggregator.cjs`) - adds lazy-loaded `proposeKfmDraftsForClusters(clusters, options)` export that invokes the KFM proposer as an additional pass after Phase 29 aggregation. Phase 29's existing 5 proposal classes are untouched (additive).
-- **Authority-watcher agent prompt** (`agents/design-authority-watcher.md`) - gains a new `Step 7.5 — Emit kfm-candidate events` section documenting the whitelist patterns + payload shape. Phase 13.2's existing fetch/diff/classify/write loop is unchanged.
+- **Authority-watcher agent prompt** (`agents/design-authority-watcher.md`) - gains a new `Step 7.5 - Emit kfm-candidate events` section documenting the whitelist patterns + payload shape. Phase 13.2's existing fetch/diff/classify/write loop is unchanged.
 - **OFF_CADENCE_VERSIONS** (`tests/semver-compare.test.cjs`) - registers `'1.30.5'` per Phase 29/30 precedent.
 
 ### Documentation
@@ -3345,7 +3377,7 @@ Closes two unrelated risks before the Phase 15–19 reference-library expansion
 **Safety hooks**
 - `hooks/gdd-bash-guard.js` - PreToolUse:Bash guard. 45 dangerous-pattern regexes across 10 families (filesystem destruction, permission escalation, pipe-to-shell, git destruction, system mutation, process nuking, credential exfil, shell obfuscation, path traversal, npm/docker/firewall abuse). `scripts/lib/dangerous-patterns.cjs` normalizes Unicode NFKC + strips ANSI escapes + strips zero-width / bidi overrides before matching so obfuscated attacks (`rm\u200B -rf /`, bidi overrides, hex-encoded `\x72\x6d\x20\x2d\x72\x66`) fail closed.
 - `hooks/gdd-protected-paths.js` + `reference/protected-paths.default.json` - PreToolUse:Edit|Write|Bash guard blocking mutation of `reference/**`, `skills/**`, `commands/**`, `hooks/**`, `.design/archive/**`, `.design/config.json`, `.design/telemetry/**`, `.git/**`, both plugin manifests. User additions in `.design/config.json.protected_paths` MERGE into the default list - users cannot reduce the default-protected set. `scripts/lib/glob-match.cjs` ships a dependency-free `**` glob matcher.
-- `scripts/lib/blast-radius.cjs` - `estimate({touchedPaths, diffStats})` + `estimateMCPCalls({toolCalls})` preflight called by `design-executor` before the first Edit/Write of each task. Defaults: `max_files_per_task: 10`, `max_lines_per_task: 400`, `max_mcp_calls_per_task: 30`. Zero-value limits disable that ceiling. `design-executor` gains a new `## Preflight — Blast-Radius Check` section.
+- `scripts/lib/blast-radius.cjs` - `estimate({touchedPaths, diffStats})` + `estimateMCPCalls({toolCalls})` preflight called by `design-executor` before the first Edit/Write of each task. Defaults: `max_files_per_task: 10`, `max_lines_per_task: 400`, `max_mcp_calls_per_task: 30`. Zero-value limits disable that ceiling. `design-executor` gains a new `## Preflight - Blast-Radius Check` section.
 
 **Injection-scanner extension**
 - `scripts/injection-patterns.cjs` extended from 7 to 22 patterns: classic prompt-injection verbs (incl. `forget previous`), **invisible-Unicode** (zero-width, BOM, bidi overrides), **HTML-comment instruction hijacks** (`<!-- system: …`, hidden divs/spans, zero-font-size tricks), **secret-exfil triggers** (`curl $OPENAI_API_KEY`, `cat .env`, `tar ~ | nc`, `process.env._KEY fetch`, SSH private-key reads). Single source of truth consumed by `hooks/gdd-read-injection-scanner.js`.
@@ -3452,7 +3484,7 @@ Cherry-picked from `c11cd7b` on `claude/upbeat-fermi-199627` - the Figma MCP fix
 
 - **URL entry point**: detect `https://api.anthropic.com/v1/design/h/<hash>` in agent prompt (native "Send to local coding agent" flow); `WebFetch` with `Content-Type` routing - HTML parsed directly, ZIP downloaded and extracted
 - **ZIP bundle**: extract to `.design/handoff/`, find primary HTML + readme, parse normally, clean up after
-- **PDF format**: `pdftotext` text extraction; grep for token values; all decisions tagged `(tentative — text-only)` since no CSS is present
+- **PDF format**: `pdftotext` text extraction; grep for token values; all decisions tagged `(tentative - text-only)` since no CSS is present
 - **PPTX format**: slide XML text extraction (`ppt/slides/*.xml`); same tentative-only tagging as PDF
 - Updated synthesizer parsing algorithm step 1 with format dispatch before parsing
 - Updated probe pattern: URL detection takes priority over file path lookup

package/README.md

@@ -307,7 +307,7 @@ Targets 50–70% per-task token-cost reduction with no quality-floor regression.
 
 ## Commands
 
-GDD ships 94 skills. The most common ones are below; for the full reference see [SKILL.md](SKILL.md).
+GDD ships 95 skills. The most common ones are below; for the full reference see [SKILL.md](SKILL.md).
 
 ### Core Pipeline
 

package/SKILL.md

@@ -99,6 +99,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `quality-gate` | `get-design-done:quality-gate` | Phase 25 - parallel lint/type/test/visual command runner; classifies failures via quality-gate-runner agent |
 | `turn-closeout` | `get-design-done:turn-closeout` | Phase 25 - Stop-hook mirror skill; finalizes per-turn STATE blocks and emits closeout events |
 | `bandit-status` | `get-design-done:bandit-status` | Phase 27.5 - read-only diagnostic surface for the bandit posterior; per-(agent, bin, delegate, tier) snapshots (alpha, beta, mean, stddev, count, last-used). Use `/gdd:bandit-reset` to mutate. |
+| `bandit-reset [--yes]` | `get-design-done:bandit-reset` | Phase 23.5 - confirm-then-reset mutation companion to `bandit-status`; backs up `.design/telemetry/posterior.json` to `posterior.json.bak`, then clears it to a fresh empty envelope so the next pull rebootstraps from informed priors. |
 | `openrouter-status [--refresh]` | `get-design-done:gdd-openrouter-status` | Phase 33.6 - read-only OpenRouter catalog + tier-mapping diagnostic; surfaces catalog freshness (vs 24h TTL), last-fetch, resolved opus/sonnet/haiku → model mappings, per-tier preview. `--refresh` re-fetches (needs `OPENROUTER_API_KEY`). |
 | `peers` | `get-design-done:peers` | Phase 27 - `/gdd:peers` capability matrix command; shows installed peer-CLIs (codex/gemini/cursor/copilot/qwen), allowlist status, claimed roles, posterior delta vs local |
 | `peer-cli-customize` | `get-design-done:peer-cli-customize` | Phase 27 - rewire role→peer mappings on a per-agent basis (edits frontmatter `delegate_to:` directly) |

package/bin/gdd-mcp

@@ -49,7 +49,18 @@ const useCompiled = fs.existsSync(compiled);
 const entry = useCompiled ? compiled : source;
 const nodeArgs = useCompiled
   ? [entry, ...process.argv.slice(2)]
-  : ['--experimental-strip-types', entry, ...process.argv.slice(2)];
+  : [
+      // Dev/source path type-strips the raw .ts. The .ts entry has no sibling
+      // package.json "type", so Node would emit a one-time
+      // MODULE_TYPELESS_PACKAGE_JSON warning. Adding {"type":"module"} is NOT a
+      // fix: it only relocates the warning to transitive .ts imports AND breaks
+      // the esbuild-CJS compiled path below. Suppress that one cosmetic warning
+      // for the server process; the compiled path needs no flag. (Phase 59.1 A4)
+      '--disable-warning=MODULE_TYPELESS_PACKAGE_JSON',
+      '--experimental-strip-types',
+      entry,
+      ...process.argv.slice(2),
+    ];
 
 const child = spawn(process.execPath, nodeArgs, {
   stdio: 'inherit',

package/bin/gdd-state-mcp

@@ -49,7 +49,18 @@ const useCompiled = fs.existsSync(compiled);
 const entry = useCompiled ? compiled : source;
 const nodeArgs = useCompiled
   ? [entry, ...process.argv.slice(2)]
-  : ['--experimental-strip-types', entry, ...process.argv.slice(2)];
+  : [
+      // Dev/source path type-strips the raw .ts. The .ts entry has no sibling
+      // package.json "type", so Node would emit a one-time
+      // MODULE_TYPELESS_PACKAGE_JSON warning. Adding {"type":"module"} is NOT a
+      // fix: it only relocates the warning to transitive .ts imports AND breaks
+      // the esbuild-CJS compiled path below. Suppress that one cosmetic warning
+      // for the server process; the compiled path needs no flag. (Phase 59.1 A4)
+      '--disable-warning=MODULE_TYPELESS_PACKAGE_JSON',
+      '--experimental-strip-types',
+      entry,
+      ...process.argv.slice(2),
+    ];
 
 const child = spawn(process.execPath, nodeArgs, {
   stdio: 'inherit',

package/connections/gdd-state.md

@@ -2,7 +2,7 @@
 
 This file is the connection specification for the `gdd-state` MCP server within the get-design-done pipeline. `gdd-state` is a **local stdio MCP server** that ships with the plugin. It exposes 11 typed tools for reading and mutating `.design/STATE.md` and emits typed telemetry events on every successful mutation. Starting in Phase 20+, `gdd-state` is the **sole mutation surface** for STATE.md — stage SKILLs stop using `Read+regex+Write` and call these tools instead.
 
-Unlike the remote/desktop connections (Figma, Refero, Preview, …), `gdd-state` is an **internal** connection: it does not reach out to any external service. It wraps the existing `scripts/lib/gdd-state/` module (see Plans 20-01, 20-02, 20-04) and emits events via `scripts/lib/event-stream/` (Plan 20-06). Every mutation tool emits a `state.mutation` event; `transition_stage` additionally emits `state.transition` on both pass and gate-veto.
+Unlike the remote/desktop connections (Figma, Refero, Preview, …), `gdd-state` is an **internal** connection: it does not reach out to any external service. It wraps the existing `sdk/state/` module (see Plans 20-01, 20-02, 20-04) and emits events via `sdk/event-stream/` (Plan 20-06). Every mutation tool emits a `state.mutation` event; `transition_stage` additionally emits `state.transition` on both pass and gate-veto.
 
 ---
 
@@ -10,7 +10,7 @@ Unlike the remote/desktop connections (Figma, Refero, Preview, …), `gdd-state`
 
 **Prerequisites:**
 
-- The `@hegemonart/get-design-done` plugin installed (the server script ships in `scripts/mcp-servers/gdd-state/`).
+- The `@hegemonart/get-design-done` plugin installed (the server script ships in `sdk/mcp/gdd-state/`).
 - Node 22+ with `--experimental-strip-types` (the server is a TypeScript file run directly via strip-types — no build step).
 
 ### Option A — Project-scoped install (dev repo)
@@ -18,7 +18,7 @@ Unlike the remote/desktop connections (Figma, Refero, Preview, …), `gdd-state`
 For local development against the plugin source tree:
 
 ```
-claude mcp add gdd-state --transport stdio "node --experimental-strip-types ./scripts/mcp-servers/gdd-state/server.ts"
+claude mcp add gdd-state --transport stdio "node --experimental-strip-types ./sdk/mcp/gdd-state/server.ts"
 ```
 
 ### Option B — Plugin-installed, global resolution
@@ -26,7 +26,7 @@ claude mcp add gdd-state --transport stdio "node --experimental-strip-types ./sc
 When the plugin is installed globally via `npm i -g @hegemonart/get-design-done`:
 
 ```
-claude mcp add gdd-state --transport stdio "node --experimental-strip-types $(npm root -g)/@hegemonart/get-design-done/scripts/mcp-servers/gdd-state/server.ts"
+claude mcp add gdd-state --transport stdio "node --experimental-strip-types $(npm root -g)/@hegemonart/get-design-done/sdk/mcp/gdd-state/server.ts"
 ```
 
 Restart the Claude Code session after install.
@@ -105,7 +105,7 @@ or
 }
 ```
 
-`kind` is one of `validation`, `state_conflict`, `operation_failed`, `unknown` — matching the GDDError taxonomy in `scripts/lib/gdd-errors/`. Callers branch on `kind` to decide whether to retry, surface to the operator, or fall back. Full Draft-07 schemas live at `scripts/mcp-servers/gdd-state/schemas/*.schema.json` and the combined manifest is at `reference/schemas/mcp-gdd-state-tools.schema.json`.
+`kind` is one of `validation`, `state_conflict`, `operation_failed`, `unknown` — matching the GDDError taxonomy in `sdk/errors/`. Callers branch on `kind` to decide whether to retry, surface to the operator, or fall back. Full Draft-07 schemas live at `sdk/mcp/gdd-state/schemas/*.schema.json` and the combined manifest is at `reference/schemas/mcp-gdd-state-tools.schema.json`.
 
 **Scoped out of Phase 20:**
 
@@ -131,10 +131,10 @@ Stage SKILL rewrites in Plans 20-07 through 20-11 will switch each skill from `R
 
 ## Fallback Behavior
 
-If the `gdd-state` MCP is **not_configured** (ToolSearch returned empty), skills fall back to the pre-Phase-20 path by importing the `scripts/lib/gdd-state/` module directly:
+If the `gdd-state` MCP is **not_configured** (ToolSearch returned empty), skills fall back to the pre-Phase-20 path by importing the `sdk/state/` module directly:
 
 ```ts
-import { read, mutate, transition } from '@hegemonart/get-design-done/scripts/lib/gdd-state/index.js';
+import { read, mutate, transition } from '@hegemonart/get-design-done/sdk/state/index.js';
 ```
 
 This path bypasses the event stream (no `state.mutation` or `state.transition` events are emitted) but preserves mutation safety through the same lockfile + atomic-rename protocol. It exists for two reasons:
@@ -171,7 +171,7 @@ preview: available
 
 ## Caveats and Pitfalls
 
-- **Do not run multiple `gdd-state` instances against the same `.design/`.** The module's lockfile (see `scripts/lib/gdd-state/lockfile.ts`) guarantees per-process safety, but spawning two separate MCP servers against the same STATE.md wastes locks and produces duplicate events. One server per Claude Code session is the design contract.
+- **Do not run multiple `gdd-state` instances against the same `.design/`.** The module's lockfile (see `sdk/state/lockfile.ts`) guarantees per-process safety, but spawning two separate MCP servers against the same STATE.md wastes locks and produces duplicate events. One server per Claude Code session is the design contract.
 
 - **Event ordering follows successful mutation, not request receipt.** `appendEvent()` is called only after `mutate()` returns successfully. A failed mutation produces a `{success:false, error}` response with no event emitted. The `state.transition` event is a deliberate exception: gate vetoes emit `state.transition` with `pass:false` because gate failures are themselves observable telemetry.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.58.1",
+  "version": "1.59.1",
   "description": "A design-quality pipeline for AI coding agents: brief, explore, plan, design, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -94,11 +94,9 @@
     "scan:outbound": "node scripts/scan-outbound-network.cjs",
     "scan:ws-bind": "node scripts/scan-ws-bind.cjs",
     "test:size-budget": "node --test test/suite/agent-size-budget.test.cjs",
-    "validate:skill-surface": "node --test test/suite/skill-surface-sync.test.cjs",
     "release:extract-changelog": "node scripts/extract-changelog-section.cjs",
     "verify:version-sync": "node scripts/verify-version-sync.cjs",
-    "typecheck:session-runner": "tsc --noEmit",
-    "gdd-sdk": "node --experimental-strip-types sdk/cli/index.ts"
+    "gdd-sdk": "node bin/gdd-sdk"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/reference/codex-tools.md

@@ -29,7 +29,7 @@ it by adding to `~/.codex/config.toml`:
 [[mcp_servers]]
 name = "gdd-state"
 command = "node"
-args = ["--experimental-strip-types", "<pkg-root>/scripts/mcp-servers/gdd-state/server.ts"]
+args = ["--experimental-strip-types", "<pkg-root>/sdk/mcp/gdd-state/server.ts"]
 ```
 
 All 11 tools exposed by the server appear as `mcp__gdd_state__*` in Codex.

package/reference/gemini-tools.md

@@ -30,7 +30,7 @@ it by adding to `~/.gemini/settings.json`:
   "mcpServers": {
     "gdd-state": {
       "command": "node",
-      "args": ["--experimental-strip-types", "<pkg-root>/scripts/mcp-servers/gdd-state/server.ts"]
+      "args": ["--experimental-strip-types", "<pkg-root>/sdk/mcp/gdd-state/server.ts"]
     }
   }
 }

package/reference/known-failure-modes.md

@@ -223,12 +223,12 @@ on them fail with a clear connection-refused class of error.
 id: KFM-008
 pattern: '(MCP.*(unreachable|ECONNREFUSED|not connected)|mcp.*server.*not.*running|connection refused.*ws://)'
 diagnosis: 'An MCP server (Figma, GDD-state, or GDD-tools) is not reachable; the plugin cannot route tool calls through it.'
-remedy: 'Start the relevant MCP server (see scripts/mcp-servers/) and confirm `claude mcp list` shows it as connected.'
+remedy: 'Start the relevant MCP server (see sdk/mcp/) and confirm `claude mcp list` shows it as connected.'
 severity: medium
 propose_report: true
 symptom: 'A command depending on an MCP server fails with `MCP unreachable`, `ECONNREFUSED`, `mcp server not running`, or `connection refused ws://...`. Tool calls routed through MCP never reach their target.'
 root_cause: 'The local MCP transport (WebSocket or stdio bridge) is not bound. The MCP server process is either not started, crashed silently, or is listening on a different port than the client expects.'
-fix: '1) Run `claude mcp list` and check the status column for the failing server. 2) If it shows `disconnected`, start it: `scripts/mcp-servers/<name>.cjs` or the launcher script for that server. 3) Confirm the port matches the value in `mcp.json` or `.mcp.json`. 4) Re-run the failing command. If the server crashes on start, this is a maintainer report path (propose_report:true).'
+fix: '1) Run `claude mcp list` and check the status column for the failing server. 2) If it shows `disconnected`, start it: `sdk/mcp/<name>/server.ts` or the launcher script for that server. 3) Confirm the port matches the value in `mcp.json` or `.mcp.json`. 4) Re-run the failing command. If the server crashes on start, this is a maintainer report path (propose_report:true).'
 related_phases: [27.7, 33.6]
 first_observed_cycle: 'pre-30.5'
 ```

package/reference/registry.json

@@ -502,7 +502,7 @@
       "path": "reference/schemas/mcp-gdd-tools.schema.json",
       "type": "schema",
       "phase": 27.7,
-      "description": "Draft-07 input/output schemas for the 12 read-only tools in scripts/mcp-servers/gdd-mcp/ (gdd-mcp MCP server)"
+      "description": "Draft-07 input/output schemas for the 12 read-only tools in sdk/mcp/gdd-mcp/ (gdd-mcp MCP server)"
     },
     {
       "name": "meta-rules",

package/reference/schemas/generated.d.ts

@@ -160,6 +160,108 @@ export interface DesignConfigJson {
 
 export type ConfigSchema = DesignConfigJson;
 
+// ---- design-context.schema.json ----
+/**
+ * The canonical typed knowledge graph of a design system, persisted at .design/context-graph.json. Nodes are design entities (tokens, components, screens, patterns); edges are typed relationships between them (uses-token, composes, transitions-to). Built by a two-phase mapper: a deterministic extract pass emits node/edge skeletons, then an LLM summary pass fills each node summary. Validated structurally by scripts/validate-design-context.cjs and queried by scripts/lib/design-context-query.cjs.
+ */
+export interface DesignContextGraph {
+  /**
+   * Schema version of this graph document (e.g. "52.0").
+   */
+  schema_version: string;
+  /**
+   * ISO-8601 timestamp the graph was last assembled (optional).
+   */
+  generated_at?: string;
+  /**
+   * All design entities in the graph. Node ids must be unique.
+   */
+  nodes: Node[];
+  /**
+   * All typed relationships. Every source/target must resolve to a node id.
+   */
+  edges: Edge[];
+  [k: string]: unknown;
+}
+export interface Node {
+  /**
+   * Stable unique identifier for the node (referenced by edge source/target).
+   */
+  id: string;
+  /**
+   * The kind of design entity this node represents.
+   */
+  type:
+    | 'token'
+    | 'component'
+    | 'variant'
+    | 'state'
+    | 'motion-fragment'
+    | 'a11y-pattern'
+    | 'screen'
+    | 'layer'
+    | 'pattern'
+    | 'anti-pattern';
+  /**
+   * Human-readable name of the entity.
+   */
+  name: string;
+  /**
+   * One-line LLM-authored description of what the entity is and does. A stub summary (empty or identical to name) is flagged by the validator as a soft warning.
+   */
+  summary: string;
+  /**
+   * Controlled-vocabulary tags grouping the node by concern (see reference/design-context-tag-vocab.md). Unknown tags are a soft warning, not a hard error.
+   */
+  tags?: string[];
+  /**
+   * Coarse complexity bucket for the entity.
+   */
+  complexity: 'simple' | 'moderate' | 'complex';
+  /**
+   * Optional finer classification. For token nodes one of color/spacing/typography/radius/shadow; for layer nodes one of Atomic/Molecular/Organism/Template. Free-form for other node types.
+   */
+  subtype?: string;
+  [k: string]: unknown;
+}
+export interface Edge {
+  /**
+   * Node id the edge originates from.
+   */
+  source: string;
+  /**
+   * Node id the edge points to.
+   */
+  target: string;
+  /**
+   * The kind of relationship between source and target.
+   */
+  type:
+    | 'uses-token'
+    | 'composes'
+    | 'extends'
+    | 'transitions-to'
+    | 'depends-on'
+    | 'mirrors'
+    | 'conflicts-with'
+    | 'referenced-by'
+    | 'tested-by'
+    | 'documented-by'
+    | 'consumes-context'
+    | 'provides-context';
+  /**
+   * Whether the relationship reads source-to-target (forward), target-to-source (backward), or both ways (bidirectional).
+   */
+  direction: 'forward' | 'backward' | 'bidirectional';
+  /**
+   * Relationship strength in the inclusive range 0..1.
+   */
+  weight: number;
+  [k: string]: unknown;
+}
+
+export type DesignContextSchema = DesignContextGraph;
+
 // ---- events.schema.json ----
 /**
  * One line of .design/telemetry/events.jsonl — the append-only telemetry stream produced by Plan 20-06. Each event is a single JSON object followed by a newline. See .planning/phases/20-gdd-sdk-foundation/20-06-PLAN.md.
@@ -168,7 +270,7 @@ export type Event = {
   [k: string]: unknown;
 } & {
   /**
-   * Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick, verify_outcome, rollout_started, rollout_advanced, rollout_stuck, budget_forecast, project_cap_warning, project_cap_halt.
+   * Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick, verify_outcome, rollout_started, rollout_advanced, rollout_stuck, budget_forecast, project_cap_warning, project_cap_halt, live_session_start, live_pick, live_generate, live_accept, live_discard, live_session_end, instinct_emitted, instinct_promoted, instinct_decayed, risk_assessment.
    */
   type: string;
   /**
@@ -266,6 +368,73 @@ export interface AgentInsightLine {
 
 export type InsightLineSchema = AgentInsightLine;
 
+// ---- instinct.schema.json ----
+/**
+ * An atomic, confidence-weighted design instinct learned across cycles. Validates the YAML frontmatter object of an instinct unit (see reference/instinct-format.md). Project-scoped units live at <root>/instincts/instincts.json; promoted global units live at ~/.claude/gdd/global-instincts.json. Persisted + queried by scripts/lib/instinct-store.cjs.
+ */
+export type InstinctUnit = {
+  [k: string]: unknown;
+} & {
+  /**
+   * Kebab-case stable identifier, e.g. "prefer-token-over-hex". Lowercase letters, digits, single hyphens.
+   */
+  id: string;
+  /**
+   * One sentence naming the situation that fires the instinct, e.g. "When a color literal appears in a component, reach for a design token first."
+   */
+  trigger: string;
+  /**
+   * Posterior trust in the instinct. Floor 0.3 (a fresh instinct is advisory, never directive); ceiling 0.9 (no instinct is ever certain). TTL decay multiplies this by 0.9 when the instinct goes unsurfaced.
+   */
+  confidence: number;
+  /**
+   * Lifecycle stage the instinct applies to, aligned to the Phase 50 lifecycle stages.
+   */
+  domain: 'intake' | 'explore' | 'decide' | 'build' | 'verify' | 'operate' | 'utility';
+  /**
+   * project = learned from one repository; global = promoted after the K/M gate across distinct projects.
+   */
+  scope: 'project' | 'global';
+  /**
+   * 8-char hex sha of the normalized git origin the instinct was first learned from. Required for project scope; optional for global (a promoted instinct is no longer tied to one origin).
+   */
+  project_id?: string;
+  /**
+   * Which producer minted the instinct: a reflection pass, the extract-learnings step, or a direct user assertion.
+   */
+  source: 'reflection' | 'extract-learnings' | 'user';
+  /**
+   * How many distinct design cycles have surfaced this instinct. Feeds the K=2 half of the promotion gate.
+   */
+  cycles_seen?: number;
+  /**
+   * Set of distinct project ids that have surfaced this instinct. Its length feeds the M=2 half of the promotion gate.
+   */
+  project_ids?: string[];
+  /**
+   * ISO date (YYYY-MM-DD) the instinct was first recorded.
+   */
+  first_seen?: string;
+  /**
+   * ISO date (YYYY-MM-DD) the instinct was last surfaced. Resets the TTL decay window.
+   */
+  last_seen?: string;
+  /**
+   * Beta posterior success weight. Seeded from the Beta(2,8) prior on promotion.
+   */
+  alpha?: number;
+  /**
+   * Beta posterior failure weight. Seeded from the Beta(2,8) prior on promotion.
+   */
+  beta?: number;
+  /**
+   * Tag recording which prior class seeded the posterior, e.g. "instinct".
+   */
+  prior_class?: string;
+};
+
+export type InstinctSchema = InstinctUnit;
+
 // ---- intel.schema.json ----
 /**
  * Shape of intel-store slice files per reference/intel-schema.md. Each slice has a generated timestamp and one array-valued payload key matching the slice name.
@@ -394,6 +563,57 @@ export interface IterationBudget {
 
 export type IterationBudgetSchema = IterationBudget;
 
+// ---- live-session.schema.json ----
+/**
+ * A single `/gdd:live` session record persisted at .design/live-sessions/<session-id>.json. Captures the pick -> generate -> accept/discard loop as an append-only event log so a session survives a crash or --resume. Written atomically by scripts/lib/live/session-store.cjs.
+ */
+export interface LiveSession {
+  /**
+   * Schema version of this session record (e.g. "47.0").
+   */
+  schema_version: string;
+  /**
+   * Stable id; also the basename of the on-disk file (no path separators).
+   */
+  session_id: string;
+  /**
+   * Lifecycle status. Only in_progress sessions are resumable.
+   */
+  status: 'in_progress' | 'completed' | 'abandoned';
+  /**
+   * ISO-8601 timestamp the session was created.
+   */
+  started_at: string;
+  /**
+   * ISO-8601 timestamp the session was closed; null while in_progress.
+   */
+  ended_at: string | null;
+  /**
+   * The page the element was picked from (optional).
+   */
+  url?: string;
+  /**
+   * Dev-server descriptor (url/port/command, or a plain string). Free-form by design.
+   */
+  dev_server?: string | {} | null;
+  /**
+   * Append-only log of session events, oldest first.
+   */
+  events: {
+    /**
+     * Event kind.
+     */
+    kind: 'pick' | 'generate' | 'accept' | 'discard';
+    /**
+     * ISO-8601 timestamp the event was recorded.
+     */
+    at: string;
+    [k: string]: unknown;
+  }[];
+}
+
+export type LiveSessionSchema = LiveSession;
+
 // ---- marketplace.schema.json ----
 /**
  * Shape of .claude-plugin/marketplace.json — the plugin marketplace descriptor.
@@ -448,7 +668,7 @@ export type McpBudgetSchema = MCPBudget;
 
 // ---- mcp-gdd-state-tools.schema.json ----
 /**
- * Combined manifest of all 11 gdd-state MCP tool input+output schemas (Plan 20-05). Individual tool schemas live under scripts/mcp-servers/gdd-state/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface.
+ * Combined manifest of all 11 gdd-state MCP tool input+output schemas (Plan 20-05). Individual tool schemas live under sdk/mcp/gdd-state/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface.
  */
 export interface McpGddStateTools {
   tools: {
@@ -482,11 +702,11 @@ export type McpGddStateToolsSchema = McpGddStateTools;
 
 // ---- mcp-gdd-tools.schema.json ----
 /**
- * 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).
+ * Combined manifest of all gdd-mcp tool input+output schemas (Plan 27.7-02). Individual tool schemas live under sdk/mcp/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).
  */
 export interface McpGddTools {
   /**
-   * Per-tool input/output schemas keyed by tool name. Exactly 12 entries (D-03 hard cap).
+   * Per-tool input/output schemas keyed by tool name. Exactly 13 entries (D-03 cap, raised 12 -> 13 in Phase 52 for gdd_context_query).
    */
   tools?: {
     gdd_status?: {
@@ -499,6 +719,22 @@ export interface McpGddTools {
         blocker_count: number;
       };
     };
+    gdd_context_query?: {
+      input: {
+        op: 'nodes' | 'edges' | 'path' | 'consumers-of' | 'unreachable' | 'cycles' | 'coverage';
+        type?: string;
+        tag?: string;
+        from?: string;
+        to?: string;
+        id?: string;
+      };
+      output: {
+        op: string;
+        graph_present: boolean;
+        path?: string;
+        result: unknown[] | {} | null;
+      };
+    };
     gdd_phase_current?: {
       input: {};
       output: {