@hegemonart/get-design-done 1.19.6 → 1.21.0

package/.claude-plugin/marketplace.json

@@ -4,15 +4,15 @@
     "name": "hegemonart"
   },
   "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). Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.19.6"
+    "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.21.0"
   },
   "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. Ships 35-component benchmark corpus with pipeline integration (auditor conformance, executor pre-flight, doc-writer scaffold, pattern-mapper convergence). Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, variable-font loading, image optimization, CSS Grid + container queries, advanced motion vocabulary, platform design patterns (iOS/Android/web/visionOS), RTL/CJK/cultural adaptations, IA catalog, form UX patterns, data-visualization matrix, and user-research methodology, 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.",
-      "version": "1.19.6",
+      "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), 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.21.0",
       "author": {
         "name": "hegemonart"
       },
@@ -62,16 +62,13 @@
         "cost-optimization",
         "cache-aware",
         "budget",
-        "component-specs",
-        "design-system-benchmarks",
-        "component-conformance",
-        "convergence-detector",
-        "i18n",
-        "user-research",
-        "information-architecture",
-        "form-patterns",
-        "data-viz",
-        "platforms"
+        "headless",
+        "cli",
+        "codex",
+        "gemini",
+        "mcp",
+        "parallel-agents",
+        "agent-sdk"
       ]
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.19.6",
-  "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Ships 35-component benchmark corpus (Waves 1–5) with pipeline integration: auditor conformance scoring, executor spec pre-flight, doc-writer scaffold, pattern-mapper convergence detector. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, variable-font loading, image optimization, CSS Grid + container queries, advanced motion vocabulary (RN MIT easings/spring/interpolate + hyperframes transition taxonomy), platform design patterns (iOS/Android/web/visionOS), RTL/CJK/cultural adaptations, information architecture catalog, form UX patterns (Wroblewski label research), data-visualization matrix (25 chart types, Okabe-Ito palette), and user-research methodology, 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.",
+  "version": "1.21.0",
+  "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.",
   "author": {
     "name": "hegemonart",
     "url": "https://github.com/hegemonart"
@@ -53,36 +53,13 @@
     "cost-optimization",
     "cache-aware",
     "budget",
-    "iconography",
-    "brand-voice",
-    "performance-budget",
-    "framer-motion",
-    "motion-design",
-    "micro-polish",
-    "surfaces",
-    "make-interfaces-feel-better",
-    "palette-catalog",
-    "style-vocabulary",
-    "industry-palettes",
-    "ui-style-vocabulary",
-    "variable-fonts",
-    "container-queries",
-    "view-transitions",
-    "motion-vocabulary",
-    "motion-easings",
-    "transition-taxonomy",
-    "gesture-mechanics",
-    "clip-path-animation",
-    "component-specs",
-    "design-system-benchmarks",
-    "component-conformance",
-    "convergence-detector",
-    "i18n",
-    "user-research",
-    "information-architecture",
-    "form-patterns",
-    "data-viz",
-    "platforms"
+    "headless",
+    "cli",
+    "codex",
+    "gemini",
+    "mcp",
+    "parallel-agents",
+    "agent-sdk"
   ],
   "skills": [
     "./skills/"

package/CHANGELOG.md

@@ -4,6 +4,144 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.21.0] — 2026-04-24
+
+Phase 21 GDD SDK Headless milestone — the plugin now runs unchanged on Claude Code, OpenAI Codex CLI, and Gemini CLI, and ships a full `gdd-sdk` CLI that executes the design pipeline without a harness. 12 plans (21-01 through 21-12), 50+ commits, 936 tests.
+
+### Added
+
+- **Headless SDK** — new `bin/gdd-sdk` CLI that runs the full design pipeline
+  without Claude Code. Subcommands: `run`, `stage <name>`, `query <op>`,
+  `audit`, `init`. Publishes as `gdd-sdk` in `package.json` `bin`. See
+  `docs/HEADLESS.md` (Phase 23 deliverable) for CI integration guidance.
+- **Session runner** (`scripts/lib/session-runner/`) — typed wrapper around
+  `@anthropic-ai/claude-agent-sdk` with USD/token budget caps, turn caps,
+  transcript capture, structured error mapping via `gdd-errors` taxonomy.
+  Emits `session.started`, `session.completed`, `session.budget_exceeded`
+  events on the shared event stream.
+- **Context engine** (`scripts/lib/context-engine/`) — per-stage file
+  manifest + markdown-aware truncation that preserves frontmatter, every
+  heading, and the first paragraph of each section for files larger than
+  8 KiB. Keeps session prompts within budget without dropping load-bearing
+  context.
+- **Tool scoping** (`scripts/lib/tool-scoping/`) — per-stage allowed-tools
+  enforcement at session creation. Verify is read-only; Explore adds web;
+  Design permits shell mutations. Per-agent frontmatter overrides via
+  `parseAgentTools()` for agent-level deviations.
+- **Structured logger** (`scripts/lib/logger/`) — leveled (debug/info/warn/
+  error) with JSONL output in headless mode, ANSI-colored stderr in
+  interactive mode. `warn`/`error` also emit `ErrorEvent` on the event
+  stream for CI consumers.
+- **Pipeline runner** (`scripts/lib/pipeline-runner/`) — brief → explore →
+  plan → design → verify state machine with retry-once, halt logic,
+  human-gate callbacks, config-driven step skipping. Emits
+  `pipeline.started`, `pipeline.completed`, `pipeline.halted`.
+- **Explore parallel runner** (`scripts/lib/explore-parallel-runner/`) —
+  4 mappers (token, component-taxonomy, a11y, visual-hierarchy) concurrent
+  with streaming synthesizer. Honors `parallelism_safe` agent frontmatter
+  for opt-in isolation.
+- **Discuss parallel runner** (`scripts/lib/discuss-parallel-runner/`) —
+  N discussant variants (user-journey, technical-constraint, brand-fit,
+  accessibility) concurrent, aggregator dedupes and clusters questions.
+- **`gdd-sdk init`** (`scripts/lib/init-runner/`) — new-project bootstrap
+  spawning 4 parallel researchers (design-system-audit, brand-context,
+  accessibility-baseline, competitive-references) + synthesizer producing
+  `.design/DESIGN-CONTEXT.md` draft.
+- **Cross-harness portability** (`scripts/lib/harness/`) — the plugin now
+  runs unchanged on Claude Code, OpenAI Codex CLI, and Gemini CLI. Ships
+  `reference/codex-tools.md`, `reference/gemini-tools.md`, `AGENTS.md`
+  (Codex), `GEMINI.md` (Gemini). The `gdd-state` MCP server works on all
+  three harnesses; harness detection is runtime-driven.
+- **E2E headless integration test** — `tests/e2e-headless.test.ts` with a
+  dry-run variant (always runs) and a live variant (gated on
+  `ANTHROPIC_API_KEY`). CI workflow gains an `e2e-headless` job.
+- **Phase 21 regression baseline** at `test-fixture/baselines/phase-21/` —
+  directory list, module list, agent list, connections list, CLI
+  subcommand list, event-type list. Enforced by
+  `tests/phase-21-baseline.test.cjs`.
+
+### Changed
+
+- `@anthropic-ai/claude-agent-sdk` added as a runtime dependency (was
+  previously only referenced in docs).
+- `package.json` `bin` now exports `gdd-sdk` in addition to
+  `get-design-done` and `gdd-state-mcp`.
+- `package.json` `files` adds `bin/` to the publish include list so the
+  `gdd-sdk` trampoline ships with the npm package.
+- `package.json` `keywords` expanded with headless / CLI / cross-harness
+  tokens (`headless`, `cli`, `codex`, `gemini`, `mcp`, `parallel-agents`,
+  `agent-sdk`) for npm search surface.
+
+### Infrastructure
+
+- New regression baseline at `test-fixture/baselines/phase-21/`.
+- CI workflow gains an `e2e-headless` job (dry-run on every PR; live on
+  main-branch push with `ANTHROPIC_API_KEY` secret).
+- `tests/semver-compare.test.cjs` `OFF_CADENCE_VERSIONS` now includes
+  `1.21.0` as the second off-cadence minor bump after `1.20.0`.
+
+---
+
+## [1.20.0] — 2026-04-24
+
+Phase 20 SDK foundation milestone — the shift from "design pipeline" to "typed SDK + MCP server + resilience primitives + event stream". 16 plans (20-00 through 20-15), 50+ commits, 645+ tests.
+
+### Added
+
+- **Resilience primitives** (headline upgrade) — pipeline now survives Anthropic API rate limits, 429 responses, and context-overflow errors without manual restart. New modules:
+  - `scripts/lib/jittered-backoff.cjs` — decorrelated-jitter exponential backoff with a pluggable clock for testability.
+  - `scripts/lib/rate-guard.cjs` — token-bucket rate limiter with `RateLimitSchema`-driven config.
+  - `scripts/lib/error-classifier.cjs` — three-class taxonomy (transient / retryable-after / fatal) mapping real Anthropic error codes.
+  - `scripts/lib/iteration-budget.cjs` — bounded-iteration guard for recovery loops with `IterationBudgetSchema`.
+  - See [`reference/error-recovery.md`](reference/error-recovery.md) for the recovery protocol.
+- **`gdd-state` MCP server** at `scripts/mcp-servers/gdd-state/` — 11 typed tools replace ad-hoc `Read + regex + Write` patterns for STATE.md:
+  - `gdd_state__get`, `__update_progress`, `__transition_stage`, `__add_blocker`, `__resolve_blocker`, `__add_decision`, `__add_must_have`, `__set_status`, `__checkpoint`, `__probe_connections`, `__frontmatter_update`.
+  - Every tool has a JSON Schema at `scripts/mcp-servers/gdd-state/schemas/`; inputs and outputs are strict-validated.
+  - Every mutation emits a typed event to `.design/telemetry/events.jsonl`.
+- **Typed state core** (`scripts/lib/gdd-state/`) — `parse()`, `serialize()`, `mutate()`, `transition()`, `read()`. Lockfile-safe concurrent writes validated by a 4-way race-condition test (`tests/race-condition-state-mutation.test.ts`) — 2000 concurrent ops, zero lost writes, <60s.
+- **Event stream foundation** — `.design/telemetry/events.jsonl` append-only with a typed `EventBus`. Parallel stream to the existing `costs.jsonl` cost telemetry.
+- **Prompt sanitizer** (`scripts/lib/prompt-sanitizer/`) — strips interactive-only constructs (AskUserQuestion, STOP, `/gdd:` slash commands) from skill bodies for future headless-runner support.
+- **TypeScript toolchain** — strict `tsconfig.json`, schema codegen to `reference/schemas/generated.d.ts`, Node 22 `--experimental-strip-types` direct execution (no bundler step).
+- **Transition gates** as pure functions (`briefToExplore`, `exploreToPlan`, `planToDesign`, `designToVerify`) with fixture-based tests.
+- **`GDDError` 3-class taxonomy** (`ValidationError`, `StateConflictError`, `OperationFailedError`) at `scripts/lib/gdd-errors/`.
+- **Phase 20 regression baseline** at `test-fixture/baselines/phase-20/` — agent list, skill list, frontmatter snapshot, MCP tools manifest (schema sha256), events schema hash, hook list, resilience primitives list. Enforced by `tests/regression-baseline-phase-20.test.cjs`.
+
+### Changed
+
+- All 5 stage skills (`brief`, `explore`, `plan`, `design`, `verify`) use `gdd_state__*` MCP tools for STATE.md operations instead of direct `Read + regex + Write`.
+- Utility skills (`pause`, `resume`, `progress`, `health`, `todo`, `settings`) migrated to typed `gdd_state__get` + mutation tools.
+- Three hooks (`budget-enforcer`, `context-exhaustion`, `gdd-read-injection-scanner`) rewritten in TypeScript and wired as event-stream consumers.
+- Four Tier-1 scripts converted to `.ts` (`tests/helpers.ts`, `scripts/validate-schemas.ts`, `scripts/validate-frontmatter.ts`, `scripts/aggregate-agent-metrics.ts`).
+- Connection probes (Figma MCP, update-check, watch-authorities) use jittered backoff instead of fixed sleeps.
+- Reflector (`agents/design-reflector.md`) reads proposals from the event stream; legacy grep path preserved as fallback.
+- `hooks.json` repointed from `.js` hooks to the new `.ts` hooks (via `--experimental-strip-types`).
+
+### Security
+
+- Lockfile-safe STATE.md mutations validated by 4-way concurrent race-condition test. Each mutation acquires `${path}.lock` (PID + timestamp), performs read-modify-write under the lock, writes to `${path}.tmp`, and atomic-renames. Windows EPERM/EBUSY from AV scanners is retried transparently.
+- Prompt sanitizer strips untrusted interactive constructs before headless execution paths — reduces prompt-injection surface for future runner work.
+
+### Fixed
+
+- Race conditions in `<position>` `task_progress` and `<blockers>` updates under parallel executor load. The prior `Read + regex + Write` pattern could lose increments and corrupt blocker counts under concurrent agent writes; the new typed `mutate()` API guarantees zero lost writes.
+
+### Deprecated
+
+- `.js` hooks under `hooks/` — replaced by `.ts` equivalents running via `--experimental-strip-types`.
+- Direct `Read → regex → Write` patterns against STATE.md — replaced by the 11 `gdd_state__*` MCP tools. Skills that still use the direct pattern will be migrated in a future phase.
+
+### Migration notes
+
+- Consumers of STATE.md should prefer the `gdd_state__*` MCP tools over direct file reads/writes — the typed tools emit events, enforce schemas, and are lockfile-safe. Direct reads for non-mutation cases remain supported.
+- Node 22+ is required for `--experimental-strip-types` execution of `.ts` scripts. The CI matrix already pins Node 22 & 24.
+- No breaking API changes. All legacy skills and agents continue to work unchanged; the MCP server is additive.
+
+### Stats
+
+- 16 plans (20-00 through 20-15) completed across 4 waves.
+- 50+ per-task commits on the Phase 20 branch.
+- 645+ tests across CJS + TS suites, 0 failures, 1 skipped.
+- `tsc --noEmit` green; `validate:schemas` 11/11 green; `validate:frontmatter` 0 violations.
 ## [1.19.6] — 2026-04-24
 
 ### Added — Design Philosophy Layer

package/README.md

@@ -29,7 +29,7 @@ npx @hegemonart/get-design-done@latest
 
 <br>
 
-[Why I Built This](#why-i-built-this) · [How It Works](#how-it-works) · [Canvas Tools](#ai-native-canvas-tools) · [Component Generators](#component-generators) · [Commands](#commands) · [Connections](#connections) · [Why It Works](#why-it-works)
+[Why I Built This](#why-i-built-this) · [How It Works](#how-it-works) · [Headless SDK](#headless-sdk) · [Canvas Tools](#ai-native-canvas-tools) · [Component Generators](#component-generators) · [Commands](#commands) · [Connections](#connections) · [Why It Works](#why-it-works)
 
 </div>
 
@@ -104,6 +104,28 @@ Built-in quality gates catch real problems: Handoff Faithfulness scoring on Clau
 - **Component generators** — 21st.dev Magic MCP adds a prior-art gate before any greenfield build; Magic Patterns generates DS-aware components with a `preview_url` for visual verification. Both feed into a shared `design-component-generator` agent.
 - **Twelve tool connections** — Four new connections (paper.design, pencil.dev, 21st.dev, Magic Patterns) join the original eight. All are optional; the pipeline degrades gracefully to fallbacks when any connection is unavailable.
 
+## What's New in v1.21.0
+
+**Headless SDK** (headline upgrade) — the plugin now ships a `gdd-sdk` CLI that runs the full design pipeline without Claude Code. Five subcommands (`run`, `stage`, `query`, `audit`, `init`) work on any CI runner with Node 22+ and an `ANTHROPIC_API_KEY`. See the [Headless SDK](#headless-sdk) section below for examples.
+
+**Parallel researchers** — four new runners execute concurrent specialized agents with a streaming synthesizer: `explore-parallel-runner` (4 mappers: token, component-taxonomy, a11y, visual-hierarchy), `discuss-parallel-runner` (N discussants: user-journey, technical-constraint, brand-fit, accessibility), and `init-runner` (4 researchers for `gdd-sdk init` bootstrap). A `pipeline-runner` state machine orchestrates brief → explore → plan → design → verify with retry-once, halt logic, and human-gate callbacks.
+
+**Cross-harness portability** — the plugin runs unchanged on Claude Code, OpenAI Codex CLI, and Gemini CLI. Codex auto-loads [`AGENTS.md`](AGENTS.md); Gemini auto-loads [`GEMINI.md`](GEMINI.md). Tool-name translations live in [`reference/codex-tools.md`](reference/codex-tools.md) and [`reference/gemini-tools.md`](reference/gemini-tools.md). The `gdd-state` MCP server works on all three harnesses.
+
+**Session primitives** — `session-runner` (typed wrapper around `@anthropic-ai/claude-agent-sdk` with USD/token budget caps, turn caps, transcript capture), `context-engine` (per-stage file manifest + markdown-aware truncation preserving frontmatter, headings, and first paragraph of each section), `tool-scoping` (per-stage allowed-tools enforcement with per-agent frontmatter overrides), and a structured `logger` (leveled, JSONL in headless mode, ANSI-colored in interactive mode).
+
+**E2E headless integration test** — `tests/e2e-headless.test.ts` with a dry-run variant (always runs) and a live variant gated on `ANTHROPIC_API_KEY`. CI gains an `e2e-headless` job.
+
+### Previously in v1.20.0
+
+**Resilience primitives** — the pipeline survives Anthropic API rate limits, 429 responses, and context-overflow errors without manual restart. Modules: jittered backoff, rate-guard, error-classifier, iteration-budget. See [`reference/error-recovery.md`](reference/error-recovery.md).
+
+**Typed state core** — `.design/STATE.md` mutations are lockfile-safe. Parallel executors concurrently update `task_progress` and `<blockers>` on the same file with zero corruption (validated by 4-way race-condition test, 2000 concurrent ops, <60s).
+
+**`gdd-state` MCP server** — 11 typed tools (`gdd_state__get`, `__update_progress`, `__transition_stage`, `__add_blocker`, `__resolve_blocker`, `__add_decision`, `__add_must_have`, `__set_status`, `__checkpoint`, `__probe_connections`, `__frontmatter_update`) replace ad-hoc STATE.md edits. Every mutation emits a typed event to `.design/telemetry/events.jsonl`.
+
+**TypeScript foundation** — `tsc --noEmit` typechecks the whole SDK; JSON schemas codegen to `reference/schemas/generated.d.ts`; hooks + Tier-1 scripts migrated to `.ts` and executed directly via Node 22 `--experimental-strip-types`.
+
 ---
 
 ## Getting Started
@@ -478,6 +500,37 @@ The watcher writes `.design/authority-report.md` — new entries classified into
 
 ---
 
+## Headless SDK
+
+Run the full GDD pipeline without Claude Code:
+
+```bash
+npx gdd-sdk init                      # bootstrap a new project
+npx gdd-sdk run                       # full pipeline (brief → verify)
+npx gdd-sdk stage explore --parallel  # single stage with parallel mappers
+npx gdd-sdk query position            # typed STATE.md read
+npx gdd-sdk audit --baseline <dir>    # regression check
+```
+
+Requires Node 22+ and an `ANTHROPIC_API_KEY`. Works on any CI runner.
+
+Internally the SDK stitches together the Phase-21 runner modules:
+`session-runner` (budget + turn cap + transcript), `context-engine` (per-stage
+file manifest + markdown truncation), `tool-scoping` (per-stage allowed-tools),
+`pipeline-runner` (brief → verify state machine with retry-once + human-gate
+callbacks), and `explore-parallel` / `discuss-parallel` / `init` for the
+concurrent researcher stages.
+
+### Cross-harness
+
+The plugin runs unchanged on Claude Code, OpenAI Codex CLI, and Gemini CLI.
+See [`reference/codex-tools.md`](reference/codex-tools.md) and
+[`reference/gemini-tools.md`](reference/gemini-tools.md) for the tool
+translations; Codex auto-loads [`AGENTS.md`](AGENTS.md) and Gemini auto-loads
+[`GEMINI.md`](GEMINI.md). The `gdd-state` MCP server works on all three.
+
+---
+
 ## AI-Native Canvas Tools
 
 get-design-done integrates with canvas tools that treat the design canvas as both source AND destination — enabling a full canvas→code→verify→canvas round-trip.

package/agents/design-reflector.md

@@ -22,6 +22,19 @@ writes:
 
 You are a post-cycle reflection agent. You analyze what happened in a design cycle, compare outcomes to costs, and produce concrete, reviewable proposals — not generic advice. Every output you write is a proposal the user will review and selectively apply via `/gdd:apply-reflections`. You never auto-apply anything.
 
+## Event-Stream Mode (Phase 20 onwards)
+
+The reflector now reads proposals from `.design/telemetry/events.jsonl` — the append-only event stream introduced by Plan 20-06. It filters entries where `type === 'reflection.proposal'`. Each matching line is a JSON object whose `payload` carries fields like `{ source: <skill|hook>, proposal_kind: <string>, rationale: <string>, ... }` emitted by the producing skill or hook.
+
+Read flow:
+
+1. Check that `.design/telemetry/events.jsonl` exists. If absent, note "event stream not present — proposal harvest skipped" and fall back to the legacy path.
+2. Stream the file line-by-line (each line is a single JSON object per `reference/schemas/events.schema.json`). Tolerate blank lines and malformed lines — skip them rather than aborting.
+3. Collect every entry where `type === 'reflection.proposal'`. Render each payload into the appropriate Proposals section below.
+4. Cross-reference the event's `stage`, `cycle`, and `_meta.source` fields when citing evidence.
+
+Legacy grep-based parsing of skill outputs is preserved as a fallback for skills that haven't yet migrated to emit `reflection.proposal` events (Phase 22 scope). If no `reflection.proposal` events are present in the stream, run the legacy harvest across `.design/learnings/*.md` and `.design/intel/` exactly as before — both paths produce the same Proposals section format.
+
 ## Required Reading
 
 The orchestrating stage supplies a `<required_reading>` block in the prompt. Read every listed file before acting — this is mandatory.

package/bin/gdd-sdk

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// bin/gdd-sdk — Plan 21-09 Task 7 (SDK-21).
+//
+// 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).
+//
+// Why a trampoline:
+//   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.
+
+'use strict';
+
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+
+const entry = path.resolve(
+  __dirname,
+  '..',
+  'scripts',
+  'lib',
+  'cli',
+  'index.ts',
+);
+
+const child = spawn(
+  process.execPath,
+  ['--experimental-strip-types', entry, ...process.argv.slice(2)],
+  { 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-sdk: failed to launch TypeScript entry:', err.message);
+  process.exit(3);
+});

package/connections/connections.md

@@ -10,6 +10,7 @@ This directory contains connection specifications for external tools and MCPs th
 
 | Connection | Status | Spec File | Notes |
 |-----------|--------|-----------|-------|
+| gdd-state | Active | [`connections/gdd-state.md`](connections/gdd-state.md) | Local stdio MCP shipped with the plugin; required for STATE.md mutation in Phase 20+ (skills fall back to direct module import when not registered) |
 | Figma | Active | [`connections/figma.md`](connections/figma.md) | Auto-detects any Figma MCP variant (remote reads+writes, desktop reads-only); prefix resolved at probe time |
 | Refero | Active | [`connections/refero.md`](connections/refero.md) | Uses `mcp__refero__*` tools (verify names via ToolSearch) |
 | Preview | Active | [`connections/preview.md`](connections/preview.md) | Uses `mcp__Claude_Preview__*` tools |
@@ -31,6 +32,7 @@ Each cell describes what the connection contributes at that pipeline stage, or `
 
 | Connection | scan | discover | plan | design | verify | canvas | generator |
 |-----------|------|----------|------|--------|--------|--------|-----------|
+| gdd-state | STATE mutation (init position, probe_connections, add_decision) | STATE mutation (add_decision, add_must_have, transition gate) | STATE mutation (locked decisions, must_haves, transition gate) | STATE mutation (update_progress, resolve_blocker, transition gate) | STATE mutation (must_have pass/fail, add_blocker, set_status) | — | — |
 | Figma | token augmentation via `get_variable_defs` (CONN-03) | decisions pre-populate via `get_variable_defs` (CONN-04) | — | write tokens/annotations/Code Connect via `use_figma` (FWR-01..04) | — | — | — |
 | Refero | — | reference search via `mcp__refero__search`; fallback → awesome-design-md (CONN-05) | — | — | — | — | — |
 | Preview | — | — | — | — | screenshots for `? VISUAL` checks (VIS-02) | — | — |
@@ -227,6 +229,7 @@ To add a new connection to the pipeline:
 - `connections/` is infrastructure scaffolding introduced in Phase 1. Stage integration (wiring detection and graceful degradation into each stage) is Phase 2 work.
 - Phase 8 added five new active connections. Linear and GitHub remain planned for a future phase.
 - Phase 14 added four AI-native design tool connections (paper.design, pencil.dev, 21st.dev, Magic Patterns) and the canvas/generator capability columns.
+- Phase 20 added `gdd-state` — a local stdio MCP server shipped with the plugin that owns STATE.md mutation across every pipeline stage. Unlike external connections, `gdd-state` is required (fallback to direct module import preserves mutation safety but loses event telemetry). See [`connections/gdd-state.md`](connections/gdd-state.md).
 - The capability matrix columns map to the five pipeline stages: `scan | discover | plan | design | verify`, plus `canvas` and `generator` sub-categories.
 
 ---

package/connections/figma.md

@@ -260,3 +260,5 @@ The `<connections>` schema is minimal by design. Traceability of which outputs c
 - **OAuth re-auth.** If `get_metadata` starts returning auth errors after previously working, the OAuth session expired. Re-running the MCP install command is not required — the session refreshes on the next tool call that returns a `reauth` hint. A clean `claude mcp remove figma && claude mcp add ...` is always safe.
 
 - **Desktop MCP reads-only.** The desktop MCP (typically `figma-desktop`) exposes read tools only. It is auto-detected by the probe and is a supported fallback when writes are not needed. Stages that require writes (figma-write) STOP with an instruction to register the remote MCP.
+
+- **Transient probe errors.** When the live `get_metadata` call errors with a transient signal (5xx, rate-limit, network timeout), retry the probe with jittered exponential backoff — use `scripts/lib/jittered-backoff.cjs` (`delayMs(attempt)` or `await sleep(attempt)`) starting at 100ms, capped at 30s, 2× growth with 20% jitter. Do NOT use a fixed 1-second sleep: synchronized siblings (watch-authorities, update-check) can trigger rate limits in lockstep. Consult `scripts/lib/rate-guard.cjs` first — if the provider is flagged as rate-limited, wait for `resetAt` before retrying rather than burning through the backoff curve.

package/connections/gdd-state.md

@@ -0,0 +1,186 @@
+# gdd-state MCP — Connection Specification
+
+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.
+
+---
+
+## Setup
+
+**Prerequisites:**
+
+- The `@hegemonart/get-design-done` plugin installed (the server script ships in `scripts/mcp-servers/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)
+
+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"
+```
+
+### Option B — Plugin-installed, global resolution
+
+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"
+```
+
+Restart the Claude Code session after install.
+
+**Configuration:**
+
+The server resolves the STATE.md path from `process.env.GDD_STATE_PATH ?? .design/STATE.md`. Resolution is relative to the server's CWD at startup. When multiple projects run concurrently, each Claude Code session spawns its own server instance rooted at that session's project directory — the env override is only needed in the rare case where STATE.md lives somewhere other than `.design/`.
+
+**Verification:**
+
+After session restart:
+
+```
+ToolSearch({ query: "mcp__gdd_state", max_results: 1 })
+```
+
+A single non-empty match is sufficient — the server ships 11 tools, all prefixed `mcp__gdd_state__`.
+
+---
+
+## Probe Pattern
+
+The `gdd-state` probe is **ToolSearch-only**. The server is local and always available once installed, so a keyword match on the tool prefix is sufficient evidence that the MCP is registered.
+
+```
+Step GS1 — ToolSearch check:
+  ToolSearch({ query: "mcp__gdd_state", max_results: 1 })
+  → Empty result     → gdd-state: not_configured  (fall back to direct import — see Fallback Behavior)
+  → Non-empty result → gdd-state: available
+
+Write gdd-state status to STATE.md <connections>.
+```
+
+No live tool call is required in the probe. Unlike Figma (which can be registered but error on auth/network), `gdd-state` is a local process — its presence in the tool list implies it will respond to calls. Each stage skill that probes should call `gdd_state__probe_connections` to write the resolved status back; the server's own probe result is recorded alongside every other connection.
+
+---
+
+## Tools
+
+Tool names are static — the server always exposes `mcp__gdd_state__<tool>`. No prefix resolution is required.
+
+| Tool                                 | Mutates? | Emits event?                     | Purpose                                                                                                     |
+| ------------------------------------ | -------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `mcp__gdd_state__get`                | No       | —                                | Read current STATE.md (parsed). Optional `{ fields: string[] }` projection.                                 |
+| `mcp__gdd_state__update_progress`    | Yes      | `state.mutation`                 | Update `<position>.task_progress` and/or `<position>.status`.                                               |
+| `mcp__gdd_state__transition_stage`   | Yes      | `state.transition` (pass + fail) | Run the gate and advance `<position>.stage` on pass. Gate-veto returns `{success:false}`; server never crashes. |
+| `mcp__gdd_state__add_blocker`        | Yes      | `state.mutation`                 | Append one entry to `<blockers>`. Defaults stage to current and date to today (UTC).                        |
+| `mcp__gdd_state__resolve_blocker`    | Yes      | `state.mutation`                 | Remove one `<blockers>` entry by 0-based index or exact text match.                                         |
+| `mcp__gdd_state__add_decision`       | Yes      | `state.mutation`                 | Append one entry to `<decisions>`. Auto-allocates `D-N`.                                                    |
+| `mcp__gdd_state__add_must_have`      | Yes      | `state.mutation`                 | Append one entry to `<must_haves>`. Auto-allocates `M-N`.                                                   |
+| `mcp__gdd_state__set_status`         | Yes      | `state.mutation`                 | Update `<position>.status`. Thin wrapper for prose that only changes status.                                |
+| `mcp__gdd_state__checkpoint`         | Yes      | `state.mutation`                 | Bump `frontmatter.last_checkpoint` and append a `<timestamps>` entry.                                       |
+| `mcp__gdd_state__probe_connections`  | Yes      | `state.mutation`                 | Merge probe results into `<connections>`. Overwrites keys; never deletes.                                   |
+| `mcp__gdd_state__frontmatter_update` | Yes      | `state.mutation`                 | Patch frontmatter fields. Rejects `pipeline_state_version` and `stage` (use `transition_stage`).            |
+
+**Tool response envelope (consistent across all 11 tools):**
+
+```json
+{
+  "success": true,
+  "data":    { /* tool-specific */ }
+}
+```
+
+or
+
+```json
+{
+  "success": false,
+  "error": {
+    "code":    "VALIDATION_STATUS_INVALID",
+    "message": "status \"running\" is not one of initialized/in_progress/completed/blocked",
+    "kind":    "validation",
+    "context": { }
+  }
+}
+```
+
+`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`.
+
+**Scoped out of Phase 20:**
+
+- `gdd_state__config_update` (mentioned in the ROADMAP prose but NOT in the numerical success criterion of "11 tools"). `.design/config.json` is a separate artifact from STATE.md; its mutation surface is tracked for Phase 21+.
+
+---
+
+## Pipeline Integration
+
+`gdd-state` is **required, not optional**. It replaces the pre-Phase-20 `Read+regex+Write` pattern that every stage skill used to mutate STATE.md by hand. Skipping this connection is the pre-Phase-20 regression path.
+
+| Stage   | Skill/Agent                           | Tool used                                                                                                                                                                                                                                                        | Purpose                                                                                                                                                             |
+| ------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| brief    | `skills/brief/SKILL.md`               | `gdd_state__get`, `gdd_state__update_progress`, `gdd_state__set_status`, `gdd_state__add_must_have`, `gdd_state__add_decision`, `gdd_state__checkpoint`, `gdd_state__transition_stage`, `gdd_state__frontmatter_update`                                        | Initialize STATE.md position; record brief-derived decisions and must-haves; gate-advance to `explore` on completion.                                                |
+| explore  | `skills/explore/SKILL.md`             | `gdd_state__get`, `gdd_state__probe_connections`, `gdd_state__add_decision`, `gdd_state__update_progress`, `gdd_state__checkpoint`, `gdd_state__transition_stage`                                                                                              | Run the 12-connection probe and write all 12 results with a single `probe_connections` call; record exploration-phase decisions; gate-advance to `plan`.             |
+| plan     | `skills/plan/SKILL.md`                | `gdd_state__get`, `gdd_state__add_decision`, `gdd_state__add_must_have`, `gdd_state__update_progress`, `gdd_state__checkpoint`, `gdd_state__transition_stage`                                                                                                  | Record locked decisions and plan-derived must-haves; gate-advance to `design`.                                                                                       |
+| design   | `skills/design/SKILL.md`              | `gdd_state__get`, `gdd_state__update_progress`, `gdd_state__checkpoint`, `gdd_state__add_decision`, `gdd_state__resolve_blocker`, `gdd_state__transition_stage`                                                                                                | Tick task_progress; resolve design-stage blockers; gate-advance to `verify`.                                                                                         |
+| verify   | `skills/verify/SKILL.md`              | `gdd_state__get`, `gdd_state__update_progress`, `gdd_state__add_must_have` (status updates), `gdd_state__add_blocker` (on failure), `gdd_state__set_status` (`completed`/`blocked`), `gdd_state__checkpoint`                                                 | Execute must-have checks, flip `pass`/`fail`, append blockers on regressions, finalize status.                                                                       |
+
+Stage SKILL rewrites in Plans 20-07 through 20-11 will switch each skill from `Read+Write` to these tools. Until those plans land, the tools are exposed but not yet consumed — Plan 20-05 ships only the surface.
+
+---
+
+## 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:
+
+```ts
+import { read, mutate, transition } from '@hegemonart/get-design-done/scripts/lib/gdd-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:
+
+1. **Standalone CLI usage.** Users running `node` scripts against the plugin outside a Claude Code session do not have MCP; the direct import lets them still mutate STATE.md safely.
+2. **Degraded operation.** If the MCP server fails to register for any reason (e.g. a session state bug), skills continue to function with the tradeoff of losing event telemetry for that session. Compared to crashing the stage, this is the right tradeoff — telemetry is observability; the STATE.md mutation is the user's primary concern.
+
+Stages do not append a `<blocker>` for a missing `gdd-state` connection — the fallback path keeps mutation safety. If a downstream consumer specifically requires events (e.g. a Phase 22+ dashboard), that consumer is responsible for surfacing the absent MCP as its own problem.
+
+---
+
+## STATE.md Integration
+
+Unlike external MCPs, `gdd-state` is the thing that **writes** to `<connections>`. Stage skills record its own probe result alongside every other connection:
+
+```xml
+<connections>
+gdd-state: available
+figma: available
+refero: not_configured
+preview: available
+</connections>
+```
+
+**Status values:**
+
+| Value            | Meaning                                                                                                        |
+| ---------------- | -------------------------------------------------------------------------------------------------------------- |
+| `available`      | `ToolSearch` returned ≥1 result matching `mcp__gdd_state`. Server is registered and tools are loadable.        |
+| `unavailable`    | Never used for `gdd-state` — the server either is or is not in the session. Reserved for symmetry.             |
+| `not_configured` | `ToolSearch` returned empty. Fall back to the direct module import; events are not emitted this session.       |
+
+---
+
+## 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.
+
+- **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.
+
+- **`frontmatter_update` cannot patch `stage`.** It returns a validation error — stages must use `transition_stage` which runs the gate and emits the right event.
+
+- **`resolve_blocker` returns `operation_failed` for no-match.** This is a non-throw failure: the caller's input was well-formed, the operation simply cannot complete. Branch on `kind === 'operation_failed'` to decide whether to retry with different inputs or surface to the operator.
+
+- **Session-id is process-level, not pipeline-level.** Every event emitted by a single server process carries the same `sessionId`. Long-running sessions will emit many events under one ID; correlation across sessions is via the cycle / stage fields, not sessionId.
+
+- **Schema files are loaded at server startup.** Edits to the per-tool JSON Schemas require a server restart to take effect. Restart the Claude Code session or re-run `claude mcp add` after schema edits.
+
+- **STATE.md path resolution.** The server resolves `.design/STATE.md` relative to its CWD at startup. If the parent Claude Code session starts in a subdirectory of your repo, set `GDD_STATE_PATH` to the absolute path to avoid "file not found" errors on the first tool call.