@hegemonart/get-design-done 1.31.0 → 1.32.0

package/bin/gdd-state-mcp

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// bin/gdd-state-mcp — Plan 31-5-05 (SDK-03, D-08); dual-mode since Plan 31-5-9.5 (D-16).
+//
+// DUAL-MODE CJS trampoline for the `gdd-state` MCP server. Resolves the server
+// entry and re-launches it under `node`, forwarding argv + exit code/signal.
+// Two modes:
+//
+//   • COMPILED (installed / packed): if the esbuild-bundled sibling
+//     `sdk/mcp/gdd-state/server.js` exists, spawn `node <js>` with NO flag.
+//     This is the path a user gets from `npm i` — the entry lives under
+//     node_modules where Node refuses --experimental-strip-types on `.ts`
+//     (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING). `prepack` compiles the .js
+//     before every pack/publish (see scripts/build-sdk-bins.cjs).
+//   • SOURCE (in-repo dev): otherwise spawn
+//     `node --experimental-strip-types sdk/mcp/gdd-state/server.ts` — raw TS, no
+//     build step, exactly as before this plan.
+//
+// Why a trampoline at all:
+//   POSIX shebangs can use `#!/usr/bin/env -S node --experimental-strip-types`,
+//   but Windows cmd.exe does not honor shebangs and npm's auto-generated .cmd
+//   shim invokes plain `node bin/gdd-state-mcp` with no way to inject the flag.
+//   Mirrors the proven bin/gdd-sdk trampoline pattern.
+
+'use strict';
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Sibling compiled JS (preferred) and the TS source (dev fallback).
+const compiled = path.resolve(
+  __dirname,
+  '..',
+  'sdk',
+  'mcp',
+  'gdd-state',
+  'server.js',
+);
+const source = path.resolve(
+  __dirname,
+  '..',
+  'sdk',
+  'mcp',
+  'gdd-state',
+  'server.ts',
+);
+
+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)];
+
+const child = spawn(process.execPath, nodeArgs, {
+  stdio: 'inherit',
+  shell: false,
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise the signal to ourselves so the parent shell sees the same
+    // termination mode (e.g., Ctrl+C propagates as SIGINT exit).
+    try {
+      process.kill(process.pid, signal);
+    } catch {
+      process.exit(1);
+    }
+    return;
+  }
+  process.exit(typeof code === 'number' ? code : 0);
+});
+
+child.on('error', (err) => {
+  // Failure to spawn node itself — extremely rare; surface to stderr.
+  // eslint-disable-next-line no-console
+  console.error('gdd-state-mcp: failed to launch MCP server entry:', err.message);
+  process.exit(3);
+});

package/{README.de.md → docs/i18n/README.de.md}

@@ -2,7 +2,7 @@
 
 # GET DESIGN DONE
 
-[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Italiano](README.it.md) · **Deutsch**
+[English](../../README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Italiano](README.it.md) · **Deutsch**
 
 **Eine Design-Quality-Pipeline für AI-Coding-Agenten: Brief → Explore → Plan → Implementierung → Verifikation.**
 

package/{README.fr.md → docs/i18n/README.fr.md}

@@ -2,7 +2,7 @@
 
 # GET DESIGN DONE
 
-[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · **Français** · [Italiano](README.it.md) · [Deutsch](README.de.md)
+[English](../../README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · **Français** · [Italiano](README.it.md) · [Deutsch](README.de.md)
 
 **Un pipeline de qualité design pour agents de code IA : brief → exploration → plan → implémentation → vérification.**
 

package/{README.it.md → docs/i18n/README.it.md}

@@ -2,7 +2,7 @@
 
 # GET DESIGN DONE
 
-[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · **Italiano** · [Deutsch](README.de.md)
+[English](../../README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · **Italiano** · [Deutsch](README.de.md)
 
 **Una pipeline di qualità del design per agenti di coding IA: brief → esplorazione → piano → implementazione → verifica.**
 

package/{README.ja.md → docs/i18n/README.ja.md}

@@ -2,7 +2,7 @@
 
 # GET DESIGN DONE
 
-[English](README.md) · [简体中文](README.zh-CN.md) · **日本語** · [한국어](README.ko.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Deutsch](README.de.md)
+[English](../../README.md) · [简体中文](README.zh-CN.md) · **日本語** · [한국어](README.ko.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Deutsch](README.de.md)
 
 **AI コーディングエージェントのためのデザイン品質パイプライン: ブリーフ → 探索 → 計画 → 実装 → 検証。**
 

package/{README.ko.md → docs/i18n/README.ko.md}

@@ -2,7 +2,7 @@
 
 # GET DESIGN DONE
 
-[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · **한국어** · [Français](README.fr.md) · [Italiano](README.it.md) · [Deutsch](README.de.md)
+[English](../../README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · **한국어** · [Français](README.fr.md) · [Italiano](README.it.md) · [Deutsch](README.de.md)
 
 **AI 코딩 에이전트를 위한 디자인 품질 파이프라인: 브리프 → 탐색 → 계획 → 구현 → 검증.**
 

package/{README.zh-CN.md → docs/i18n/README.zh-CN.md}

@@ -2,7 +2,7 @@
 
 # GET DESIGN DONE
 
-[English](README.md) · **简体中文** · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Deutsch](README.de.md)
+[English](../../README.md) · **简体中文** · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Deutsch](README.de.md)
 
 **面向 AI 编码智能体的设计质量流水线:简报 → 探索 → 规划 → 实现 → 验证。**
 

package/hooks/_hook-emit.js

@@ -45,7 +45,7 @@ function getAppendEvent() {
     // require()'ing — if Node refuses to parse `.ts`, we silently fall
     // back to no-op.
     // eslint-disable-next-line node/no-missing-require, global-require
-    cachedAppendEvent = require('../scripts/lib/event-stream/index.ts').appendEvent;
+    cachedAppendEvent = require('../sdk/event-stream/index.ts').appendEvent;
     return cachedAppendEvent;
   } catch {
     cachedAppendEvent = null;

package/hooks/budget-enforcer.ts

@@ -44,8 +44,8 @@ import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
 import { createRequire } from 'node:module';
 
-import { appendEvent } from '../scripts/lib/event-stream/index.ts';
-import type { HookFiredEvent } from '../scripts/lib/event-stream/index.ts';
+import { appendEvent } from '../sdk/event-stream/index.ts';
+import type { HookFiredEvent } from '../sdk/event-stream/index.ts';
 // Consume the generated BudgetSchema so this hook participates in the
 // Plan 20-00 codegen graph. We treat parsed JSON as BudgetSchema after
 // the structural merge with defaults — the schema permits every field
@@ -71,7 +71,7 @@ function resolveHookPath(): string {
 }
 const nodeRequire = createRequire(resolveHookPath());
 const rateGuard = nodeRequire('../scripts/lib/rate-guard.cjs') as typeof import('../scripts/lib/rate-guard.cjs');
-const iterationBudget = nodeRequire('../scripts/lib/iteration-budget.cjs') as typeof import('../scripts/lib/iteration-budget.cjs');
+const iterationBudget = nodeRequire('../sdk/primitives/iteration-budget.cjs') as typeof import('../sdk/primitives/iteration-budget.cjs');
 // Plan 26-05: shared cost-computation backend for the resolved_models
 // consumer path. Pure module — takes (model_id, runtime, token_counts) →
 // cost_usd by reading per-runtime price tables under reference/prices/.
@@ -612,9 +612,9 @@ export function writeTelemetry(partial: TelemetryRowPartial): void {
 
 /**
  * Emit one hook.fired event per hook decision. Uses the pre-registered
- * HookFiredEvent subtype from scripts/lib/event-stream/types.ts and
+ * HookFiredEvent subtype from sdk/event-stream/types.ts and
  * stamps sessionId from the process PID + boot time — same scheme as
- * scripts/mcp-servers/gdd-state/tools/shared.ts but inlined here so the
+ * sdk/mcp/gdd-state/tools/shared.ts but inlined here so the
  * hook stays dependency-light.
  */
 let CACHED_SESSION_ID: string | null = null;

package/hooks/context-exhaustion.ts

@@ -28,8 +28,8 @@ import {
 import { dirname, join } from 'node:path';
 import { createInterface } from 'node:readline';
 
-import { appendEvent } from '../scripts/lib/event-stream/index.ts';
-import type { HookFiredEvent } from '../scripts/lib/event-stream/index.ts';
+import { appendEvent } from '../sdk/event-stream/index.ts';
+import type { HookFiredEvent } from '../sdk/event-stream/index.ts';
 
 // ── Types ───────────────────────────────────────────────────────────────────
 

package/hooks/gdd-precompact-snapshot.js

@@ -6,7 +6,7 @@
  * writes an atomic snapshot of STATE.md sections + last-N event-chain
  * entries + last-N decisions to `.design/snapshots/<ts>.json`.
  *
- * Phase 27.6 D-08: atomic .tmp + rename via scripts/lib/lockfile.cjs.
+ * Phase 27.6 D-08: atomic .tmp + rename via sdk/primitives/lockfile.cjs.
  *   - Lockfile serializes concurrent PreCompact writers.
  *   - .tmp + rename guarantees no partial file ever appears at target path
  *     (a SIGKILL between writeFileSync and renameSync leaves an orphan
@@ -52,7 +52,7 @@ function detectHarness() {
 
 function getAppendEvent() {
   try {
-    const m = require('../scripts/lib/event-stream');
+    const m = require('../sdk/event-stream');
     if (m && typeof m.appendEvent === 'function') return m.appendEvent;
   } catch {
     /* swallow — event-stream is optional infrastructure */
@@ -224,7 +224,7 @@ async function main() {
   // PreCompact writers; the second writer either waits or fails-silent.
   let release = null;
   try {
-    const lockfile = require('../scripts/lib/lockfile.cjs');
+    const lockfile = require('../sdk/primitives/lockfile.cjs');
     release = await lockfile.acquire(snapshotPath, {
       staleMs: 60_000,
       maxWaitMs: 10_000,

package/hooks/gdd-read-injection-scanner.ts

@@ -29,8 +29,8 @@ import { createRequire } from 'node:module';
 import { createInterface } from 'node:readline';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 
-import { appendEvent } from '../scripts/lib/event-stream/index.ts';
-import type { HookFiredEvent } from '../scripts/lib/event-stream/index.ts';
+import { appendEvent } from '../sdk/event-stream/index.ts';
+import type { HookFiredEvent } from '../sdk/event-stream/index.ts';
 
 // ── require-bridge to the shared .cjs pattern file ──────────────────────────
 

package/hooks/gdd-sessionstart-recap.js

@@ -45,7 +45,7 @@ function detectHarness() {
 
 function getAppendEvent() {
   try {
-    const m = require('../scripts/lib/event-stream');
+    const m = require('../sdk/event-stream');
     if (m && typeof m.appendEvent === 'function') return m.appendEvent;
   } catch {
     /* swallow — event-stream is optional infrastructure */

package/hooks/gdd-turn-closeout.js

@@ -49,7 +49,7 @@ const TAIL_BYTES = 8_192; // last 8 KiB is plenty for one event line (<<64KiB ca
  * Lightweight parse of the `<position>` block in STATE.md. Returns the fields
  * we care about, or null if the block isn't present / well-formed.
  *
- * We intentionally avoid the full parser at scripts/lib/gdd-state/parser.ts
+ * We intentionally avoid the full parser at sdk/state/parser.ts
  * because (a) it requires TS execution and (b) its overhead would blow the
  * 10ms budget. The position block is k=v lines so a regex pass is fine.
  */

package/hooks/hooks.json

@@ -32,6 +32,15 @@
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-sessionstart-recap.js\""
           }
         ]
+      },
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/inject-using-gdd.sh\""
+          }
+        ]
       }
     ],
     "PreToolUse": [

package/hooks/inject-using-gdd.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# hooks/inject-using-gdd.sh — SessionStart per-harness context injector (D-07).
+#
+# The forcing function GDD lacked: on every session start / /clear / compact this
+# reads skills/using-gdd/SKILL.md (the bootstrap discipline contract) and emits it
+# as the host harness's SessionStart "additionalContext" shape so the agent is
+# primed with the 1%-rule + red-flags + skill-priority before it acts.
+#
+# Ported MECHANISM (not content) from obra/superpowers (MIT): one polyglot script,
+# env-var branch, pure-bash escape_for_json (no jq/python dependency). See NOTICE.
+#
+# Three emitted shapes (ONE JSON object on stdout, nothing else):
+#   Cursor       (CURSOR_PLUGIN_ROOT set)        -> {"additional_context": "<escaped>"}
+#   Claude Code  (CLAUDE_PLUGIN_ROOT set, no Cursor)
+#                                                -> {"hookSpecificOutput":
+#                                                     {"hookEventName":"SessionStart",
+#                                                      "additionalContext":"<escaped>"}}
+#   SDK-standard (neither; e.g. COPILOT_CLI)     -> {"additionalContext": "<escaped>"}
+#
+# Branch order: check Cursor BEFORE Claude Code — a Cursor session may also export
+# CLAUDE_PLUGIN_ROOT, and Cursor's own var must win.
+#
+# NO-CASCADE (D-06): this script is wired ONLY under the SessionStart hook event in
+# hooks/hooks.json. Subagent spawns do not fire SessionStart, so the inject cannot
+# cascade into a subagent's context. (Structural guarantee; behavioral proof = P33.)
+
+set -u
+
+# --- Resolve the plugin root so we can locate skills/using-gdd/SKILL.md ---------
+# Prefer the harness-provided roots; fall back to this script's parent dir so the
+# emitter is runnable straight from hooks/ in tests and in bare shells.
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="${CURSOR_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${SELF_DIR}/..}}"
+ROOT="${ROOT//\\//}"  # normalize Windows backslashes to forward slashes
+SKILL="${ROOT}/skills/using-gdd/SKILL.md"
+
+# Defensive: if the skill file is missing we must STILL emit a syntactically valid
+# JSON object (an empty additionalContext) so the SessionStart pipeline never
+# breaks on a partial install. Never crash the session start.
+if [[ -r "${SKILL}" ]]; then
+  CONTENT="$(cat "${SKILL}")"
+else
+  CONTENT=""
+fi
+
+# --- escape_for_json (superpowers pattern; pure bash param-substitution) --------
+# Order matters: backslash FIRST (so escapes we add next aren't re-escaped), then
+# double-quote, then the control chars newline / tab / carriage-return. Emits the
+# value WITH surrounding double-quotes so callers can splice it directly.
+escape_for_json() {
+  local s="$1"
+  s="${s//\\/\\\\}"   # \  -> \\
+  s="${s//\"/\\\"}"   # "  -> \"
+  s="${s//$'\t'/\\t}" # tab -> \t
+  s="${s//$'\r'/\\r}" # CR  -> \r
+  s="${s//$'\n'/\\n}" # LF  -> \n  (do last: newlines are the record separator)
+  printf '"%s"' "$s"
+}
+
+ESCAPED="$(escape_for_json "${CONTENT}")"
+
+# --- Branch on harness env vars and emit the matching single JSON object --------
+if [[ -n "${CURSOR_PLUGIN_ROOT:-}" ]]; then
+  # Cursor: top-level additional_context.
+  printf '{"additional_context": %s}\n' "${ESCAPED}"
+elif [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
+  # Claude Code: hookSpecificOutput envelope (mirrors hooks/gdd-decision-injector.js).
+  printf '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": %s}}\n' "${ESCAPED}"
+else
+  # SDK-standard (COPILOT_CLI or none): top-level additionalContext.
+  printf '{"additionalContext": %s}\n' "${ESCAPED}"
+fi

package/hooks/run-hook.cmd

@@ -0,0 +1,35 @@
+@echo off
+REM hooks/run-hook.cmd — Windows polyglot wrapper that invokes a GDD .sh hook
+REM through bash.
+REM
+REM Workaround for Claude Code's Windows auto-bash bug: CC can mis-handle a
+REM SessionStart `command` that points directly at a `.sh` file on Windows
+REM shells. This .cmd shim locates bash and runs the script explicitly, so the
+REM SessionStart inject (hooks/inject-using-gdd.sh) fires on Windows too.
+REM
+REM Usage:  run-hook.cmd <script-name.sh> [args...]
+REM Default (no arg): inject-using-gdd.sh — the SessionStart using-gdd injector.
+REM The host harness's env (CLAUDE_PLUGIN_ROOT / CURSOR_PLUGIN_ROOT / COPILOT_CLI)
+REM is inherited by bash and drives the emitter's per-harness branch.
+setlocal
+
+REM Script to run, relative to this .cmd's own directory (%~dp0 ends with a backslash).
+set "HOOK_SCRIPT=%~1"
+if "%HOOK_SCRIPT%"=="" set "HOOK_SCRIPT=inject-using-gdd.sh"
+if not "%~1"=="" shift
+
+set "HOOK_PATH=%~dp0%HOOK_SCRIPT%"
+
+REM Prefer bash on PATH; fall back to a typical Git-for-Windows install location.
+where bash >nul 2>nul
+if %ERRORLEVEL%==0 (
+  bash "%HOOK_PATH%" %*
+) else if exist "%ProgramFiles%\Git\bin\bash.exe" (
+  "%ProgramFiles%\Git\bin\bash.exe" "%HOOK_PATH%" %*
+) else (
+  REM No bash available: emit a valid empty SDK-shape JSON object so the
+  REM SessionStart pipeline still receives parseable output and never breaks.
+  echo {"additionalContext": ""}
+)
+
+endlocal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.31.0",
+  "version": "1.32.0",
   "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",
@@ -17,21 +17,28 @@
     "agents/",
     "skills/",
     "hooks/",
-    "scripts/",
     "connections/",
     "reference/",
     "bin/",
+    "sdk/",
+    "recipes/",
+    "docs/i18n/",
+    "scripts/lib/",
+    "scripts/mcp-servers/",
+    "scripts/cli/",
+    "scripts/install.cjs",
     "SKILL.md",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ],
   "bin": {
     "gdd-events": "./scripts/cli/gdd-events.mjs",
     "gdd-graph": "./bin/gdd-graph",
-    "gdd-mcp": "./scripts/mcp-servers/gdd-mcp/server.ts",
+    "gdd-mcp": "./bin/gdd-mcp",
     "gdd-sdk": "./bin/gdd-sdk",
-    "gdd-state-mcp": "./scripts/mcp-servers/gdd-state/server.ts",
+    "gdd-state-mcp": "./bin/gdd-state-mcp",
     "get-design-done": "./scripts/install.cjs"
   },
   "publishConfig": {
@@ -40,26 +47,30 @@
   },
   "scripts": {
     "build:bundles": "node scripts/build-distribution-bundles.cjs",
-    "test": "node --test --experimental-strip-types \"tests/**/*.test.cjs\" \"tests/**/*.test.ts\"",
+    "build:sdk": "node scripts/build-sdk-bins.cjs",
+    "prepack": "npm run build:sdk",
+    "postpack": "node scripts/build-sdk-bins.cjs --clean",
+    "test": "node --test --experimental-strip-types \"test/suite/**/*.test.cjs\" \"test/suite/**/*.test.ts\"",
     "typecheck": "tsc --noEmit",
     "codegen:schemas": "node --experimental-strip-types scripts/codegen-schema-types.ts",
-    "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#.planning\" \"#.claude\" \"#test-fixture/baselines\"",
+    "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#.planning\" \"#.claude\" \"#test/fixtures/baselines\"",
     "lint:links": "npx --yes lychee --no-progress --accept 200,206,403,429 \"**/*.md\" || true",
     "lint:agentskills": "node scripts/lint-agentskills-spec.cjs",
     "validate:schemas": "node --experimental-strip-types scripts/validate-schemas.ts",
     "validate:frontmatter": "node --experimental-strip-types scripts/validate-frontmatter.ts agents/",
     "detect:stale-refs": "node scripts/detect-stale-refs.cjs",
     "scan:injection": "node scripts/run-injection-scanner-ci.cjs",
-    "test:size-budget": "node --test tests/agent-size-budget.test.cjs",
+    "test:size-budget": "node --test test/suite/agent-size-budget.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 scripts/lib/cli/index.ts"
+    "gdd-sdk": "node --experimental-strip-types sdk/cli/index.ts"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
     "ajv-cli": "^5.0.0",
     "ajv-formats": "^3.0.1",
+    "esbuild": "^0.25.12",
     "json-schema-to-typescript": "^15.0.0",
     "typescript": "^6.0.3"
   },

package/reference/schemas/events.schema.json

@@ -10,7 +10,7 @@
     "type": {
       "type": "string",
       "minLength": 1,
-      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap."
+      "description": "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."
     },
     "timestamp": {
       "type": "string",
@@ -181,6 +181,57 @@
         }
       },
       "description": "Phase 30.5-03 D-06 kfm-candidate payload — 7 fields, additionalProperties: false. Validated when the envelope's type === 'kfm-candidate' via the allOf[1] conditional."
+    },
+    "RouterPickPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "event_id",
+        "source",
+        "picked_skill",
+        "context_hash",
+        "rank",
+        "alternatives",
+        "ts"
+      ],
+      "properties": {
+        "event_id": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+          "description": "UUIDv4 identifying this router_pick event. Stable across emit + read cycles."
+        },
+        "source": {
+          "type": "string",
+          "const": "router",
+          "description": "Phase 32-08 D-02 — the router_pick event class is emitted EXCLUSIVELY by the gdd-router skill at its resolved-pick point. No other producer is authorised."
+        },
+        "picked_skill": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The skill or agent the router auto-picked for this intent. Phase 33 baselines per-skill auto-pick rates from this field (pick-rate regression)."
+        },
+        "context_hash": {
+          "type": "string",
+          "minLength": 1,
+          "description": "sha256 of the intent/context that drove the pick — NEVER the raw prompt (no PII, mirrors CapabilityGapPayload.context_hash discipline). Used by Phase 33 aggregation to cluster picks for the same context."
+        },
+        "rank": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Rank of the picked_skill among the candidates considered (0 = top pick). Lets Phase 33 distinguish confident top picks from close calls."
+        },
+        "alternatives": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Other candidate skill/agent names the router considered (names only — no scores, no prompt text). May be empty when the router had a single match. Surfaces which skills the router weighs but does not reach for."
+        },
+        "ts": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 timestamp of the pick emission."
+        }
+      },
+      "description": "Phase 32-08 D-02 router_pick payload — 7 fields, additionalProperties: false, NO PII (context_hash only). Records which skill the router auto-picked per intent — the instrument that surfaces under-reached skills. Validated when the envelope's type === 'router_pick' via the allOf[2] conditional."
     }
   },
   "allOf": [
@@ -205,6 +256,17 @@
           "payload": { "$ref": "#/definitions/KfmCandidatePayload" }
         }
       }
+    },
+    {
+      "if": {
+        "properties": { "type": { "const": "router_pick" } },
+        "required": ["type"]
+      },
+      "then": {
+        "properties": {
+          "payload": { "$ref": "#/definitions/RouterPickPayload" }
+        }
+      }
     }
   ]
 }

package/reference/schemas/recipe.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/hegemonart/get-design-done/main/reference/schemas/recipe.schema.json",
+  "title": "Recipe",
+  "description": "Shape of a declarative recipe loaded from recipes/<name>.json by scripts/lib/recipe-loader.cjs (Plan 31-5-03, RECIPE-01 / SC#14). The recipes/ directory ships EMPTY of recipes and is populated downstream by Phase 32 (skill-trigger recipes), Phase 33.6 (per-provider), Phase 26 (per-runtime/per-model), and Phase 23.5 (bandit-arm shape). This is a minimal, forward-compatible envelope: a recipe MUST carry name/version/steps; additionalProperties:true lets the populating phases extend the envelope without breaking the loader contract. Modelled on Storybloq's src/autonomous/recipes/ loader.ts pattern.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["name", "version", "steps"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The recipe identifier. Matches the filename stem (recipes/<name>.json)."
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Recipe/schema version string for forward-compatibility. Lets the loader and downstream phases reason about envelope evolution."
+    },
+    "steps": {
+      "type": "array",
+      "description": "The ordered recipe body. Item shape is kept permissive for now — each step is an object carrying at least a `kind` OR an `id` string. Downstream phases (32/33.6/26/23.5) tighten the step contract per their domain.",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "anyOf": [
+          { "required": ["kind"], "properties": { "kind": { "type": "string", "minLength": 1 } } },
+          { "required": ["id"], "properties": { "id": { "type": "string", "minLength": 1 } } }
+        ]
+      }
+    }
+  }
+}

package/scripts/cli/gdd-events.mjs

@@ -138,7 +138,7 @@ export function compileFilter(terms) {
 
 async function cmdTail(parsed) {
   const path = resolvePath(parsed.flags.path);
-  const { readEvents } = await import('../lib/event-stream/reader.ts');
+  const { readEvents } = await import('../../sdk/event-stream/reader.ts');
   if (!parsed.flags.follow) {
     for await (const ev of readEvents({ path })) {
       stdout.write(JSON.stringify(ev) + '\n');
@@ -188,7 +188,7 @@ async function cmdGrep(parsed) {
     return 2;
   }
   const predicate = compileFilter(terms);
-  const { readEvents } = await import('../lib/event-stream/reader.ts');
+  const { readEvents } = await import('../../sdk/event-stream/reader.ts');
   for await (const ev of readEvents({ path, predicate })) {
     stdout.write(JSON.stringify(ev) + '\n');
   }
@@ -197,7 +197,7 @@ async function cmdGrep(parsed) {
 
 async function cmdCat(parsed) {
   const path = resolvePath(parsed.flags.path);
-  const { readEvents } = await import('../lib/event-stream/reader.ts');
+  const { readEvents } = await import('../../sdk/event-stream/reader.ts');
   for await (const ev of readEvents({ path })) {
     const ts = ev.timestamp ?? '?';
     const tp = ev.type ?? '?';
@@ -207,7 +207,7 @@ async function cmdCat(parsed) {
 }
 
 async function cmdListTypes() {
-  const { KNOWN_EVENT_TYPES } = await import('../lib/event-stream/types.ts');
+  const { KNOWN_EVENT_TYPES } = await import('../../sdk/event-stream/types.ts');
   for (const t of KNOWN_EVENT_TYPES) stdout.write(t + '\n');
   return 0;
 }
@@ -236,7 +236,7 @@ async function cmdServe(parsed) {
   // Bridge live bus → ws transport. The transport is CommonJS and cannot
   // require .ts directly, so we import the bus here and pass subscribeAll
   // as a callback factory.
-  const { subscribeAll } = await import('../lib/event-stream/index.ts');
+  const { subscribeAll } = await import('../../sdk/event-stream/index.ts');
   const subscribe = (handler) => subscribeAll(handler);
   const handle = await mod.startServer({ port, token, tailFrom, subscribe });
   stderr.write(`gdd-events: WebSocket listening on :${port} (auth required)\n`);

package/scripts/lib/cache/gdd-cache-manager.cjs

@@ -83,7 +83,7 @@ function clamp01(n) {
 function getAppendEvent() {
   try {
     // Resolved relative to this file: `scripts/lib/cache/` → `../event-stream`.
-    const m = require('../event-stream');
+    const m = require('../../../sdk/event-stream');
     if (m && typeof m.appendEvent === 'function') return m.appendEvent;
   } catch {
     // Swallow — fall through to the no-op below. The event is