@hegemonart/get-design-done 1.31.0 → 1.31.5

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.31.0"
+    "version": "1.31.5"
   },
   "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.31.0",
+      "version": "1.31.5",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.31.0",
+  "version": "1.31.5",
   "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. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.31.5] - 2026-05-29
+
+### Phase 31.5 — Repo Structure Consolidation
+
+One audit-clean repo layout with **zero changes to the public surface** (commands, agents, skills, hooks, connections, install flow) and **no file content lost**. The SDK that `plugin.json` has advertised since v1.20.0 now actually lives in `sdk/`; the npm tarball ships only what plugin users need; the repo root is decluttered. Every move was history-preserving (`git mv`), guarded by three independent regression nets (test-parity, tarball-diff golden, headless-E2E install) and a one-minor deprecation-shim grace window. 10 plans + 1 follow-up across Waves A–E (31-5-01..31-5-10 + 31-5-9.5).
+
+### Added
+
+- **`sdk/` — the public SDK, collected.** `git mv` consolidated the strewn modules into one place: `sdk/cli`, `sdk/state`, `sdk/event-stream`, `sdk/errors`, `sdk/primitives/*` (the 4 typed `.cjs`+`.d.cts` pairs), and **both** MCP servers under `sdk/mcp/` (`sdk/mcp/gdd-state`, `sdk/mcp/gdd-mcp` — D-08). A `sdk/index.ts` barrel re-exports the surface, and `sdk/README.md` (≤120 lines, D-06) documents what the SDK is with a per-module import-path table (module → public import → helpers → stability tag). Public import paths are explicit per-module (`/sdk/cli`, `/sdk/state`, `/sdk/event-stream`, `/sdk/primitives/*`, `/sdk/errors`, `/sdk/mcp/gdd-state`, `/sdk/mcp/gdd-mcp`) plus the barrel (D-04).
+- **3 SDK bins that now work from an npm install.** `bin/gdd-sdk`, `bin/gdd-state-mcp`, and `bin/gdd-mcp` are dual-mode trampolines (prefer a compiled `.js` sibling, fall back to `.ts` strip in-repo). A `prepack` step (`npm run build:sdk` → esbuild) bundles the three TS-entry bins to self-contained CommonJS siblings that ship in the tarball — fixing a **pre-existing latent break**: raw `.ts` bins cannot run under `--experimental-strip-types` from inside `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), which had silently shipped since the TS bins were introduced. The `.ts` remain the source of truth; the `.js` are gitignored build artifacts (`postpack` cleans them).
+- **`recipes/` scaffold** — `recipes/` + a recipe-loader + `reference/schemas/recipe.schema.json`. Ships empty of recipes (the loading machinery, not content).
+- **`docs/i18n/`** — the 6 `README.{de,fr,it,ja,ko,zh-CN}.md` translations relocated from the repo root (D-11). English `README.md` stays at root; its language-selector links were repointed.
+- **`.npmignore`** — a defense-in-depth duplicate of the `package.json` `files` allowlist (D-10).
+- **Private-files CI guard** — `test/suite/no-private-files-tracked.test.cjs` asserts 0 tracked `.planning/` / `REVIEW.md` / `tmp_support_preview*` files so the (already-remediated) leak stays closed (D-03).
+- **`no-stale-internal-refs` static guard** — `test/suite/no-stale-internal-refs.test.cjs` greps the shipped user-facing surface (hooks/, agents/, skills/, bin/, scripts/cli/, scripts/install.cjs) for any reference to an OLD moved-SDK path and fails on any hit outside a deprecation shim. Proves every internal caller was repointed to `sdk/`.
+
+### Changed
+
+- **`package.json` `files` narrowed to an explicit allowlist (+ `.npmignore`).** Maintainer-only top-level scripts no longer reach a user's `node_modules`. **Tarball diff vs the prior (v1.31.0) tarball:**
+  - **ADDED:** `sdk/` (the SDK, incl. the 3 compiled-bin `.js` siblings), `recipes/`, `docs/i18n/`, `NOTICE`.
+  - **DROPPED (23 maintainer-only files):** `scripts/` wholesale + the top-level `bootstrap*`, `rollback-release.sh`, `apply-branch-protection.sh`, `release-smoke-test.cjs`, `verify-version-sync.cjs`, `extract-changelog-section.cjs`, `detect-stale-refs.cjs`, `run-injection-scanner-ci.cjs`, `injection-patterns.cjs`, `build-*.cjs`, `validate-*` (`.cjs`/`.ts`), `codegen-schema-types.ts`, `aggregate-agent-metrics.ts`, `lint-agentskills-spec.cjs`, `scripts/e2e/`, `scripts/tests/`.
+  - **KEPT (runtime subtrees, D-09) — a "drop `scripts/` wholesale" allowlist would have shipped a *broken* package:** `scripts/lib/` (incl. `scripts/lib/graph/` for `gdd-graph` per D-14 and `scripts/lib/figma-extract/` for the figma-extract SKILL per D-15), `scripts/mcp-servers/` (the residual MCP deprecation shims), `scripts/cli/` (the `gdd-events` target), and `scripts/install.cjs`.
+  - Tarball golden manifest pinned at **620 paths** (paths-only per D-07).
+- **`tests/` → `test/suite/` and `test-fixture/` → `test/fixtures/`** (D-12) — a pure mechanical, history-preserving relocation done with an identical full-suite pass before/after. Contributor-facing only; not shipped in the tarball. All subsequent tests are authored into `test/suite/`.
+
+### Deprecated
+
+- **`scripts/lib/{cli,gdd-state,event-stream,gdd-errors}/`, the 4 primitive `.cjs` (`error-classifier`, `iteration-budget`, `jittered-backoff`, `lockfile`), and `scripts/mcp-servers/{gdd-state,gdd-mcp}/server.ts` are now thin deprecation shims** that re-export from `sdk/*` and emit a one-time `DeprecationWarning`. They exist for undocumented EXTERNAL importers who reached into `node_modules/.../scripts/lib/...` directly. **Removed in v1.33.0** (D-02). Grace window: v1.31.5 ships with shims → v1.32.0 still has them → v1.33.0 removes them with a breaking-change note. **If you imported from `node_modules/@hegemonart/get-design-done/scripts/lib/...` directly, switch to `sdk/...`** (e.g. `scripts/lib/cli` → `sdk/cli`, `scripts/lib/error-classifier.cjs` → `sdk/primitives/error-classifier.cjs`, `scripts/mcp-servers/gdd-state/server.ts` → `sdk/mcp/gdd-state/server.ts`). Internal callers already use `sdk/`.
+
+### Backward compatibility
+
+- Public surface unchanged — no command, agent, skill, hook, or connection was renamed (zero-rename discipline). All install flows and all 6 bins resolve identically; MCP handshakes and primitive imports verified by the headless pack→install→run E2E.
+- 6-manifest lockstep at v1.31.5 (`package.json` + `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` (metadata.version + plugins[0].version) + `.cursor-plugin/plugin.json` + `.codex-plugin/plugin.json`).
+
+### Decisions
+
+- **D-01**: Target version is **v1.31.5** (the stale ROADMAP v1.28.0 was a pre-renumber artifact — the phase was renumbered 2026-05-16 to monotonic-with-phase-number).
+- **D-02**: Deprecation-shim removal target is **v1.33.0** (the stale ROADMAP v1.29.0 is already shipped/past). One-minor grace window.
+- **D-03**: The private-file leak was already remediated on main; Plan 01 ships only the CI guard.
+- **D-08**: `gdd-mcp` (Phase 27.7) folded in for full symmetry with `gdd-state-mcp` — both MCP servers live under `sdk/mcp/`.
+- **D-09**: The `files` allowlist keeps the runtime subtrees `scripts/lib` + `scripts/mcp-servers` + `scripts/cli` + `scripts/install.cjs` so `gdd-graph`, `figma-extract`, and `gdd-mcp` keep working.
+
+---
+
 ## [1.31.0] - 2026-05-29
 
 ### Phase 31 — Figma Off-Context Extractor + Variables Sync Plugin

package/NOTICE

@@ -0,0 +1,224 @@
+get-design-done
+Copyright (c) 2026 hegemonart
+
+This product includes software developed by third parties under the
+Apache License, Version 2.0. See https://www.apache.org/licenses/LICENSE-2.0
+for the full license text.
+
+──────────────────────────────────────────────────────────────────────────────
+Phase 27 — Peer-CLI Delegation Layer (v1.27.0, 2026-04-30)
+──────────────────────────────────────────────────────────────────────────────
+
+The peer-CLI delegation layer ports protocol shapes and skill patterns from:
+
+  greenpolo/cc-multi-cli-plugin (https://github.com/greenpolo/cc-multi-cli-plugin)
+  License: Apache License, Version 2.0
+  Version reference: cc-multi-cli v2.0.0 (shipped 2026-04-24)
+
+The following gdd files re-derive logic, contracts, or procedural patterns
+from cc-multi-cli's source. We re-derive in our own runtime (CommonJS in
+gdd's case; cc-multi-cli ships ESM); we do NOT vendor their runtime —
+their hub assumes Claude-as-host while gdd needs any-runtime-as-host.
+Attribution is provided here per Apache 2.0 §4.
+
+  scripts/lib/peer-cli/acp-client.cjs
+    └─ Adapts the line-delimited JSON-RPC + initialize/prompt/notification
+       framing from cc-multi-cli's `acp-client.mjs`.
+
+  scripts/lib/peer-cli/asp-client.cjs
+    └─ Adapts the App Server Protocol thread-start + thread-resume + turn
+       lifecycle from cc-multi-cli's `asp-client.mjs`. service_name and
+       experimentalRawEvents conventions match cc-multi-cli.
+
+  scripts/lib/peer-cli/spawn-cmd.cjs
+    └─ Implements the Windows `.cmd` EINVAL workaround documented in
+       cc-multi-cli's `transport-decisions.md`
+       (`spawn(`"<absolute-fwd-slash-path>" <args>`, [], {shell: true})`).
+
+  skills/peer-cli-customize/SKILL.md
+    └─ Procedural pattern adapted from cc-multi-cli's `customize` skill.
+
+  skills/peer-cli-add/SKILL.md
+    └─ Procedural pattern adapted from cc-multi-cli's `multi-cli-anything`
+       skill, including the verification ladder, model-ID `-preview`-suffix
+       trap, and Windows quirk handling.
+
+──────────────────────────────────────────────────────────────────────────────
+Phase 28.5 — Skill Authoring Contract + Rework + Project Artifacts (v1.28.5, 2026-05-18)
+──────────────────────────────────────────────────────────────────────────────
+
+The skill-authoring contract, project-artifact format files, the
+debug-feedback-loops reference, and the new zoom-out micro-skill port
+content from:
+
+  mattpocock/skills (https://github.com/mattpocock/skills)
+  License: MIT
+  Adapted with permission.
+
+The following gdd files contain content adapted from mattpocock/skills:
+
+  reference/skill-authoring-contract.md
+    └─ Adapts the SKILL.md <=100-line cap, description-format contract
+       (lax-mode default per Phase 33 A/B pending), frontmatter required
+       fields, and progressive-disclosure-one-level-deep rules from
+       mattpocock's productivity/write-a-skill/SKILL.md.
+
+  reference/context-md-format.md
+    └─ Adapts mattpocock's productivity/grill-with-docs/CONTEXT-FORMAT.md
+       (DDD-style ubiquitous-language glossary schema, inline-write
+       trigger, multi-context CONTEXT-MAP.md pattern). GDD additions:
+       optional first-seen + aliases on term entries.
+
+  reference/adr-format.md
+    └─ Adapts mattpocock's productivity/grill-with-docs/ADR-FORMAT.md
+       (3-criteria offer gate: hard-to-reverse AND surprising-without-
+       context AND real-tradeoff; 4-state status lifecycle). GDD
+       additions: optional cycle-id + phase-id cross-refs back to
+       STATE.md.
+
+  reference/architecture-vocabulary.md
+    └─ Ports Ousterhout's *A Philosophy of Software Design* glossary via
+       mattpocock's improve-codebase-architecture/LANGUAGE.md (8 core
+       terms — Module / Interface / Implementation / Depth / Seam /
+       Adapter / Leverage / Locality — plus 3 principles: deletion test,
+       interface-is-test-surface, two-adapters-rule).
+
+  reference/debug-feedback-loops.md
+    └─ Adapts mattpocock's engineering/diagnose Phase 1 — feedback-loop
+       discipline, 10 construction paths in priority order (failing test
+       -> curl -> CLI fixture -> headless browser -> trace replay ->
+       throwaway harness -> fuzz -> bisect harness -> differential loop
+       -> HITL bash), iterate-on-loop sub-discipline, non-determinism
+       reproduction-rate branch.
+
+  skills/zoom-out/SKILL.md
+    └─ Direct port of mattpocock's engineering/zoom-out (~10 lines body,
+       disable-model-invocation: true, zoom-out-and-map-the-area
+       instruction). User-invoked-only shortcut.
+
+  skills/debug/SKILL.md (Phase 1 ordering)
+    └─ Adopts the feedback-loop-discipline-first ordering — build the
+       deterministic, fast, agent-runnable signal before hypothesizing.
+       (Skill body itself is GDD original; the Phase 1 ordering +
+       cross-link to reference/debug-feedback-loops.md is adapted.)
+
+──────────────────────────────────────────────────────────────────────────────
+Phase 28.7 — Multi-Runtime Install Architecture (v1.28.7, 2026-05-19)
+──────────────────────────────────────────────────────────────────────────────
+
+The multi-runtime install pipeline shipped in v1.28.7 — the runtime-homes /
+runtime-artifact-layout / runtime-slash trio plus the per-runtime content
+converters — is a re-implementation of the architecture from:
+
+  gsd-build/get-shit-done (https://github.com/gsd-build/get-shit-done)
+  License: MIT
+
+The following gdd modules are an architectural port from gsd-build's MIT-
+licensed install machinery. We re-implemented in GDD's existing module
+conventions rather than byte-copying source, per Phase 28.7 D-02, to keep
+the GDD codebase free of upstream version drift and the bundled
+`bin/install.js` monolith:
+
+  scripts/lib/install/runtime-homes.cjs
+    └─ Per-runtime config-dir resolver (env-var + XDG + special-case nests).
+       Same shape as gsd-build's `bin/lib/runtime-homes.cjs`.
+
+  scripts/lib/install/runtime-artifact-layout.cjs
+    └─ Per-(runtime, scope) layout table mapping to kinds[]. Same shape as
+       gsd-build's `bin/lib/runtime-artifact-layout.cjs`. Adapted to GDD's
+       14-runtime set (gsd-build's Hermes is omitted per D-03 + D-10).
+
+  scripts/lib/install/runtime-slash.cjs
+    └─ Per-runtime slash-command surface emitter. Adapted from gsd-build's
+       `bin/lib/runtime-slash.cjs`. Codex uses `$gdd-<name>` shell-var form;
+       other runtimes use `/gdd-<name>`.
+
+  scripts/lib/install/converters/{antigravity,augment,cline,codebuddy,codex,
+                                  copilot,cursor,gemini,kilo,opencode,qwen,
+                                  shared,trae,windsurf}.cjs
+    └─ Per-runtime content converters. Each translates a Claude SKILL.md
+       source into the runtime's expected shape (path rewrite, tool-name
+       rewrite via Phase 21 cross-harness maps, frontmatter pass-through).
+       gsd-build implements these as `convertClaudeCommandTo<Runtime>Skill`
+       functions inside a bundled `bin/install.js`; we factor them into
+       per-runtime `.cjs` files for independent testability.
+
+Per-file headers in the ported modules carry the same attribution. This
+NOTICE block is the rollup citation.
+
+The upstream gsd-build project remains the authoritative reference for the
+install-pipeline architecture; bug reports specific to the architecture's
+shape should also be filed there.
+
+──────────────────────────────────────────────────────────────────────────────
+Phase 30 — Privacy Layer (v1.30.0, 2026-05-20)
+──────────────────────────────────────────────────────────────────────────────
+
+scripts/lib/pseudonymize.cjs and scripts/lib/issue-reporter/payload-assembly.cjs
+were authored from scratch for Phase 30 (consent-first issue reporter). No
+third-party privacy or anonymization patterns were adapted into either file
+— verified by inspection of the file contents (no "adapted from" / "from
+<library>" / source-citation comments) and by git log on both files (commits
+ed478fe, e5fc79a, e86c648 — all original to this repo).
+
+The regex rules in pseudonymize.cjs target generic identity-correlatable
+fields (usernames, hostnames, filesystem paths, repo origin URLs, env-var
+values, email patterns, IP addresses). The patterns were derived from the
+canonical shapes of these surfaces as they appear in plugin runtime output;
+they were NOT sourced from any upstream anonymization or pseudonymization
+library.
+
+The Phase 30 — Inbound Feedback Channel design itself (consent-first issue
+reporter, hardcoded destination, no plugin-side credentials, gh-CLI-only
+outbound) is original to get-design-done. The architectural rationale lives
+in .planning/phases/30-issue-reporter/CONTEXT.md.
+
+──────────────────────────────────────────────────────────────────────────────
+Phase 30.6 — Graphify Self-Ownership (v1.30.6, 2026-05-28)
+──────────────────────────────────────────────────────────────────────────────
+
+Version 1.30.6 removes the last runtime touchpoint between get-design-done
+and the user's `~/.claude/get-shit-done/` install. Eight callsites
+previously dispatched `node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs"
+graphify *` at runtime; they now dispatch a native `bin/gdd-graph` CLI
+owned end-to-end in this repository.
+
+No historical MIT/Apache attributions in this NOTICE are removed or
+modified by this change. The Phase 27 / Phase 28.5 / Phase 28.7
+attribution subsections above are preserved verbatim per Phase 30.6 D-06.
+Those describe historical architectural ports:
+
+  - Phase 27 — peer-CLI delegation protocol shapes adapted from
+    cc-multi-cli-plugin (Apache 2.0).
+  - Phase 28.5 — skill-authoring contract + project-artifact formats +
+    debug feedback-loop reference + zoom-out micro-skill, ported from
+    mattpocock/skills (MIT).
+  - Phase 28.7 — multi-runtime install pipeline architecture, ported
+    from gsd-build/get-shit-done (MIT).
+
+Phase 30.6 removes a runtime touchpoint, NOT a historical port. The
+architectural ports listed above remain in our tree under their original
+MIT/Apache terms.
+
+For context: the upstream `gsd-build/get-shit-done` project has since been
+archived (TÂCHES rug-pull, May 2026). The community continuation lives at
+`open-gsd/get-shit-done-redux` and is bit-perfect with the pre-rug tree.
+The Phase 28.7 attribution above remains pointed at the original upstream
+URL because that is the source of the architectural port; the redux fork
+is referenced in `README.md` for users seeking a current download.
+
+See `.planning/phases/30.6-graphify-self-ownership/` for full phase
+documentation including the 10 architectural decisions (D-01 through D-10)
+and the migration of the 8 dispatching callsites to native `bin/gdd-graph`.
+
+────────────────────────────────────────────────────────────────────────
+
+Note on the broader codebase: get-design-done as a whole is licensed under
+the MIT License (see LICENSE). The Apache 2.0 attribution above applies
+specifically to the cc-multi-cli-derived files listed under the Phase 27
+block. The MIT attributions under Phase 28.5 and Phase 28.7 cover content
+adapted from mattpocock/skills (MIT) and gsd-build/get-shit-done (MIT)
+respectively — the MIT-to-MIT re-licensing is straightforward and the
+attributions above provide the required source citation. The MIT and
+Apache 2.0 licenses are compatible — see
+https://www.apache.org/legal/resolved.html#category-a.

package/README.md

@@ -2,7 +2,7 @@
 
 # GET DESIGN DONE
 
-**English** · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Deutsch](README.de.md)
+**English** · [简体中文](docs/i18n/README.zh-CN.md) · [日本語](docs/i18n/README.ja.md) · [한국어](docs/i18n/README.ko.md) · [Français](docs/i18n/README.fr.md) · [Italiano](docs/i18n/README.it.md) · [Deutsch](docs/i18n/README.de.md)
 
 **A design-quality pipeline for AI coding agents: brief → explore → plan → implement → verify.**
 

package/agents/design-authority-watcher.md

@@ -194,7 +194,7 @@ After classifying the new entries (Step 5) but BEFORE writing the snapshot (Step
 - `/known issues/i`
 - `/pitfalls/i`
 
-For each entry whose `title` matches ANY pattern, emit a single `kfm-candidate` event to the events stream (`.design/telemetry/events.jsonl`) via `scripts/lib/event-stream/writer.ts` (or the Bash equivalent — `printf '%s\n' "<json>" >> .design/telemetry/events.jsonl`).
+For each entry whose `title` matches ANY pattern, emit a single `kfm-candidate` event to the events stream (`.design/telemetry/events.jsonl`) via `sdk/event-stream/writer.ts` (or the Bash equivalent — `printf '%s\n' "<json>" >> .design/telemetry/events.jsonl`).
 
 Event payload shape — validates against `reference/schemas/events.schema.json` definitions `KfmCandidatePayload` (allOf[1] branch). Required 7 fields:
 

package/agents/perf-analyzer.md

@@ -80,7 +80,7 @@ For each regression, emit a `perf.regression_detected` event via `appendEvent` f
 
 ```javascript
 // Pseudo-instruction for the executor — the agent runs Bash with this shape
-const { appendEvent } = require('./scripts/lib/event-stream');
+const { appendEvent } = require('./sdk/event-stream');
 appendEvent({
   type: 'perf.regression_detected',
   timestamp: new Date().toISOString(),
@@ -89,7 +89,7 @@ appendEvent({
 });
 ```
 
-The `perf.regression_detected` event type is additive to the Phase 22 registry — the writer accepts unknown types (per `scripts/lib/event-stream/types.ts` envelope invariant: "unknown types are allowed; validation is structural, not a closed enum").
+The `perf.regression_detected` event type is additive to the Phase 22 registry — the writer accepts unknown types (per `sdk/event-stream/types.ts` envelope invariant: "unknown types are allowed; validation is structural, not a closed enum").
 
 If `detectCostRegressions` returns `summary.regressions_count === 0`, write a single line: `No token-cost regressions detected (threshold 25%, >=3 cycles).` and skip event emission for this section.
 

package/bin/gdd-mcp

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// bin/gdd-mcp — Plan 31-5-05 (SDK-04, D-08); dual-mode since Plan 31-5-9.5 (D-16).
+//
+// DUAL-MODE CJS trampoline for the `gdd-mcp` 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-mcp/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-mcp/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-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-mcp',
+  'server.js',
+);
+const source = path.resolve(
+  __dirname,
+  '..',
+  'sdk',
+  'mcp',
+  'gdd-mcp',
+  '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-mcp: failed to launch MCP server entry:', err.message);
+  process.exit(3);
+});

package/bin/gdd-sdk

@@ -1,37 +1,47 @@
 #!/usr/bin/env node
-// bin/gdd-sdk — Plan 21-09 Task 7 (SDK-21).
+// bin/gdd-sdk — Plan 21-09 Task 7 (SDK-21); dual-mode since Plan 31-5-9.5 (D-16).
 //
-// CJS trampoline: spawns `node --experimental-strip-types` against the
-// real TS entry point in `scripts/lib/cli/index.ts` and forwards argv +
-// exit code. Windows-compatible (npm's generated .cmd shim on Windows
-// has no way to inject the --experimental-strip-types flag otherwise).
+// DUAL-MODE CJS trampoline. Resolves the SDK CLI entry and re-launches it under
+// `node`, forwarding argv + exit code/signal. Two modes:
 //
-// Why a trampoline:
+//   • COMPILED (installed / packed): if the esbuild-bundled sibling
+//     `sdk/cli/index.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/cli/index.ts` — the 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. npm's auto-generated
-//   .cmd shim invokes plain `node bin/gdd-sdk` without passing the
-//   experimental flag. The trampoline re-launches node with the flag
-//   explicitly so both platforms end up at the same TS entry.
+//   but Windows cmd.exe does not honor shebangs and npm's auto-generated .cmd
+//   shim invokes plain `node bin/gdd-sdk` with no way to inject the flag. The
+//   trampoline re-launches node correctly on both platforms.
 
 'use strict';
 
 const { spawn } = require('node:child_process');
+const fs = require('node:fs');
 const path = require('node:path');
 
-const entry = path.resolve(
-  __dirname,
-  '..',
-  'scripts',
-  'lib',
-  'cli',
-  'index.ts',
-);
+// Sibling compiled JS (preferred) and the TS source (dev fallback).
+const compiled = path.resolve(__dirname, '..', 'sdk', 'cli', 'index.js');
+const source = path.resolve(__dirname, '..', 'sdk', 'cli', 'index.ts');
+
+// fs.existsSync (not a try/require) — the entry is launched in a child node,
+// not require()'d here, and we must not evaluate it in this process.
+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,
-  ['--experimental-strip-types', entry, ...process.argv.slice(2)],
-  { stdio: 'inherit', shell: false },
-);
+const child = spawn(process.execPath, nodeArgs, {
+  stdio: 'inherit',
+  shell: false,
+});
 
 child.on('exit', (code, signal) => {
   if (signal) {
@@ -50,6 +60,6 @@ child.on('exit', (code, signal) => {
 child.on('error', (err) => {
   // Failure to spawn node itself — extremely rare; surface to stderr.
   // eslint-disable-next-line no-console
-  console.error('gdd-sdk: failed to launch TypeScript entry:', err.message);
+  console.error('gdd-sdk: failed to launch SDK CLI entry:', err.message);
   process.exit(3);
 });

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 코딩 에이전트를 위한 디자인 품질 파이프라인: 브리프 → 탐색 → 계획 → 구현 → 검증.**