@hegemonart/get-design-done 1.19.5 → 1.20.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.5"
+    "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.20.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.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), 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.20.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.19.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. 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.20.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"

package/CHANGELOG.md

@@ -4,6 +4,96 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [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
+
+Adds a generative reasoning spine on top of the defensive (anti-patterns) and descriptive (heuristics) layers. Purely additive knowledge + lens integration — no new agents, skills, or commands.
+
+**New `reference/first-principles.md`:** 3-invariant framework (body / attention / memory) with grep-able principle→code pairs and a reducibility test for every design element. Wired into `design-discussant` as Step 0.5 — three invariant questions prepended to the brief-stage interview; answers recorded as `[Invariant]` D-XX decisions in STATE.md.
+
+**New `reference/emotional-design.md`:** Don Norman's visceral / behavioral / reflective three-level framework as a cross-cutting scoring lens. Per-level scoring rubrics (1–4) and a cross-level conflict table. Wired into `design-auditor` (Step 4.5 Emotional Design Overlay appended to DESIGN-AUDIT.md) and `design-reflector` (visceral/behavioral divergence check in Section 1).
+
+**New `reference/component-authoring.md`:** Emil Kowalski / Sonner 6-principle component quality standard — P-01 Minimal API, P-02 Composability, P-03 Defaults, P-04 Animation as State, P-05 Accessibility First, P-06 Edge Honesty — with grep-able audit signals and an ARIA contract table by component type. Wired into design-auditor (Pillar 7 sub-check), design-discussant (`--spec` mode question), and design-verifier must-have checklist.
+
+**`reference/heuristics.md` extended:** Added Peak-End Rule, Loss Aversion, Cognitive Load Theory (intrinsic / extraneous / germane), Aesthetic-Usability Effect, Doherty Threshold (400ms), and Flow (Csikszentmihalyi) — completing the psychology foundations layer.
+
+**`reference/motion-advanced.md`:** Disney's 12 Principles UX mapping stub replaced with full authoring — all 12 principles translated to interface motion with code examples (Squash and Stretch, Anticipation, Staging, Straight Ahead vs Pose to Pose, Follow Through, Slow In/Slow Out, Arcs, Secondary Action, Timing, Exaggeration, Solid Drawing, Appeal).
+
+**`reference/checklists.md`:** Added Rams Lens (10 questions mapping Dieter Rams's principles) and Sonner / Component-Authoring Lens (6 P-0N questions) as post-audit self-checks.
+
+**`reference/shared-preamble.md`:** Added Design Philosophy Layer block pointing to the three new reference files — ensures all agents are aware of the philosophy spine.
+
+**`reference/authority-feeds.md`:** Added `jnd.org` (Don Norman) and `vitsoe.com` (Dieter Rams / Vitsœ) as named-practitioner feeds. Feed count: 26 → 28.
+
+**`design-auditor`:** Required reading expanded with `reference/emotional-design.md` and `reference/component-authoring.md`. Step 4.5 (Emotional Design Overlay) added to execution steps.
+
+**`design-discussant`:** Step 0.5 (First-Principles Invariants) prepends three invariant questions during brief/discover stage.
+
+**`design-reflector`:** Section 1 extended with four principles-check prompts: reducibility, memory-load, peak-end, and error-redemption.
+
+---
+
 ## [1.19.5] — 2026-04-24
 
 ### Added — Cross-Cycle Memory: Recall, Checkpoints, Experience Archive

package/README.md

@@ -104,6 +104,18 @@ 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.20.0
+
+**Resilience primitives** (headline upgrade) — the pipeline now survives Anthropic API rate limits, 429 responses, and context-overflow errors without manual restart. New modules: jittered backoff, rate-guard, error-classifier, iteration-budget. See [`reference/error-recovery.md`](reference/error-recovery.md) for the recovery protocol. Connection probes and long-running loops use these primitives instead of fixed sleeps.
+
+**Typed state core** — `.design/STATE.md` mutations are now lockfile-safe. Parallel executors can concurrently update `task_progress` and `<blockers>` on the same file with zero corruption — validated by a 4-way race-condition test (2000 concurrent ops, <60s). The legacy `Read → regex → Write` pattern is deprecated in favor of the typed API.
+
+**`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`, giving downstream consumers a structured audit trail next to the existing `costs.jsonl` cost stream.
+
+**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` (no bundler step).
+
+**Prompt sanitizer** — strips interactive-only constructs (AskUserQuestion, STOP, `/gdd:` slash commands) from skill bodies. Preparatory work for headless-runner support.
+
 ---
 
 ## Getting Started

package/agents/design-auditor.md

@@ -62,6 +62,8 @@ Minimum expected files:
 - `reference/data-visualization.md` — chart-choice matrix, color-blind palettes, axis conventions (use for chart-heavy projects)
 - `reference/rtl-cjk-cultural.md` — RTL mirroring, CJK typography, cultural color meanings (use when i18n or multi-locale is in scope)
 - `reference/information-architecture.md` — nav pattern catalog, menu-depth rules, wayfinding (use when nav structure is in scope)
+- `reference/emotional-design.md` — Norman's visceral/behavioral/reflective cross-cutting lens; apply after pillar scoring as an informational overlay (see Emotional Design Overlay section below)
+- `reference/component-authoring.md` (if present) — Kowalski/Sonner P-01–P-06 principles; apply as sub-check within Pillar 7 (Micro-Polish) for component-heavy UIs
 
 ---
 
@@ -334,6 +336,16 @@ For each of the 7 pillars:
 
 Write `.design/DESIGN-AUDIT.md` using the output format below.
 
+### Step 4.5: Emotional Design Overlay
+
+After pillar scoring, apply the three-level lens from `reference/emotional-design.md`:
+
+1. **Visceral** — map Pillar 3 (Color) + Pillar 2 (Visual Hierarchy) → does the aesthetic surface convey the intended emotional register within 3 seconds?
+2. **Behavioral** — map Pillar 6 (Experience Design) + H-01/H-09 signals → does feedback arrive within 400ms? Are errors human-readable?
+3. **Reflective** — is there a designed peak moment in the primary flow? Does brand voice carry through to empty states?
+
+Emit a `## Emotional Design Overlay` section in DESIGN-AUDIT.md (informational; does not affect /28 score). Flag any cross-level conflict (e.g., high behavioral + low visceral) as a priority finding.
+
 ### Step 5: Emit Completion Marker
 
 After writing the file, emit `## AUDIT COMPLETE` as the final line of the response.

package/agents/design-discussant.md

@@ -32,6 +32,20 @@ The spawning prompt supplies `<required_reading>`. Read every listed file before
 
 If `<connections>` in STATE.md shows `figma: available`, read the `prefix=` field on that line (call it `{P}`). Then `ToolSearch({ query: "figma get_variable_defs", max_results: 5 })` and call `{P}get_variable_defs`. For each returned variable, draft a *tentative* D-XX decision (mark "tentative — confirm with user"). Silently skip on any error. Do NOT grep the codebase.
 
+## Step 0.5 — First-Principles Invariants (brief stage only)
+
+If `<stage>` in the spawning prompt is `brief` or `discover`, prepend these three invariant questions **before** the main design interview. Record answers as D-XX decisions prefixed `[Invariant]` in STATE.md.
+
+Read `reference/first-principles.md` before asking. Questions to ask (one at a time, using `AskUserQuestion`):
+
+1. **Body invariant** — "Are there accessibility requirements for motor-impaired users, or will this be used primarily on mobile devices? (This affects minimum touch target sizes and input method assumptions.)"
+2. **Attention invariant** — "What is the single most important action a user should take on the primary screen? (This will be the only element styled as a primary action.)"
+3. **Memory invariant** — "Are there any multi-step flows where users must carry information from one screen to the next? (This determines whether we need progress indicators or inline context cues.)"
+
+After recording all three answers, apply the **Reducibility Test** framing: note in STATE.md which design elements are invariant-justified (body/attention/memory) and which are decorative.
+
+Skip this step if: `<stage>` is not `brief`/`discover`, if `<mode>` is `--from-handoff` (handoff decisions already encode invariants), or if D-XX decisions prefixed `[Invariant]` already exist in STATE.md.
+
 ## Step 1 — Mode dispatch
 
 Inspect the orchestrator prompt for `<mode>`:

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.
@@ -51,6 +64,16 @@ Write these sections in order. If source data is missing, write the section head
 
 Compare `.design/DESIGN-VERIFICATION.md` gaps to `.design/DESIGN-PLAN.md` acceptance criteria. List decisions that deviated from plan, unexpected cost spikes (agent cost > 2× typical), agents that ran > 3× their `typical-duration-seconds`. One bullet per surprise; cite cycle slug and evidence.
 
+After listing standard surprises, apply the **Four Principles Checks** from `reference/emotional-design.md` and `reference/first-principles.md`:
+
+**Reducibility check** — Did any executed task add elements that fail the reducibility test (body / attention / memory justification absent)? If DESIGN-PLAN.md tasks added >3 visual elements none of which appear in DESIGN-VERIFICATION.md acceptance criteria, flag as "possible decorative accumulation."
+
+**Memory-load check** — Does DESIGN-VERIFICATION.md show any H-06 (Recognition > Recall) gap? If yes, flag: "Memory invariant violation — users may need to remember context between screens." Cite the specific gap.
+
+**Peak-End check** — Scan DESIGN-PLAN.md and DESIGN-VERIFICATION.md for evidence of a designed peak moment (a completion screen, a celebration, a distinct success state). If none found, flag: "No peak moment designed — reflective-level experience may score low. Consider adding a designed end state."
+
+**Error-redemption check** — Scan DESIGN-VERIFICATION.md for H-09 (Error Recovery) score. If score < 3, flag: "Error-redemption gap — error states do not guide users to resolution. This is a behavioral-level failure that also damages the reflective level (users remember bad endings)."
+
 ### 2. Recurring Decisions
 
 Scan STATE.md `<decisions>` block for D-XX codes. Cross-reference `.design/learnings/` files from prior cycles if present. Flag decisions that: (a) appeared in multiple sessions of the same cycle, or (b) appear under the same keyword in learnings from ≥2 prior cycles. These are candidates for `reference/` additions.

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.