@hegemonart/get-design-done 1.51.0 → 1.52.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.51.0"
+    "version": "1.52.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. 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.51.0",
+      "version": "1.52.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.51.0",
+  "version": "1.52.0",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 59 specialized agents, 88 skills, 41 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Slack, Linear, Jira, Notion, and more), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.52.0] - 2026-06-03
+
+### Phase 52 - Typed DesignContext Graph Schema (KEYSTONE)
+
+GDD's design knowledge lived in flat `.design/map/*.md` mapper notes that nothing downstream could query. Phase 52
+introduces a typed DesignContext graph: a design-semantic map of tokens, components, variants, states, motion fragments,
+a11y patterns, screens, layers, and design patterns, plus the typed edges between them. It is the keystone for phases
+53-57 (semantic mapper engine, graph-aware verification, dashboard, SQLite mirror). Regex extraction (not tree-sitter),
+JSON storage (not SQLite), zero new dependency. Planned and executed via the GSD pipeline (5 parallel executor subagents).
+
+### Breaking changes
+
+- **New graph contract at `.design/context-graph.json`.** Nodes are `{ id, type, name, summary, tags[], complexity }`
+  over 10 node types; edges are `{ source, target, type, direction, weight }` over 12 edge types
+  (`reference/schemas/design-context.schema.json`). The 5 mapper agents and the synthesizer now DUAL-EMIT: they keep
+  writing `.design/map/*.md` AND emit graph fragments to `.design/fragments/<mapper>.json` (backward-compatible for one
+  minor version), so consumers gain the graph without losing the markdown maps.
+- **gdd-mcp tool cap raised 12 -> 13.** A 13th read-only tool, `gdd_context_query`, joins the registry
+  (`sdk/mcp/gdd-mcp/tools/index.ts`). The hard cap in the tool index, the MCP-tools lint, and the Phase 27.7 baselines
+  all move to 13. No write tools were added.
+
+### Added
+
+- **Schema, validator, query lib**: `reference/schemas/design-context.schema.json` (plus `reference/design-context-schema.md`
+  and `reference/design-context-tag-vocab.md`); `scripts/validate-design-context.cjs` (referential integrity, id
+  uniqueness, completeness, controlled tag vocabulary; dep-free with an optional Ajv overlay; wired as the
+  `validate:design-context` CI gate, a clean no-op when no graph is present); and `scripts/lib/design-context-query.cjs`
+  (`load`/`nodes`/`edges`/`path`/`consumersOf`/`unreachable`/`cycles`/`coverage`; pure, dep-free).
+- **Extract and merge engine**: `scripts/lib/design-context/{extract-tokens,extract-components,extract-motion,extract-a11y,extract-visual-hierarchy,merge-fragments,integration-map}.mjs`,
+  regex over source roots, dep-free, emitting schema-valid fragments; merge dedupes nodes by id and recovers or drops dangling edges.
+- **MCP and skills**: `gdd_context_query` (read-only graph query over the seven operations), `/gdd:context` (its front
+  end), and `/gdd:migrate-context` (migrate a pre-Phase-52 project from `.design/map/*.md` to the graph, flagging
+  low-confidence transforms; preview-first with `--dry-run`).
+- **Debt-crawler dual-mode**: `design-debt-crawler` queries the graph when `.design/context-graph.json` is present and
+  falls back to grep otherwise; `/gdd:progress` surfaces graph coverage; `integration-map.mjs` renders a mermaid map per Atomic-Design layer.
+
+### Notes
+
+- 6-manifest lockstep at **v1.52.0** + `OFF_CADENCE_VERSIONS.add('1.52.0')` + 37 `manifests-version.txt` baselines.
+  Re-locked: skill-list (89 -> 91; +context +migrate-context), root SKILL.md rows, the phase-42 compile count
+  (113 -> 115), the phase-28.5 distribution + warn count (8 -> 10; context at 137 and migrate-context at 123 lines, both
+  in the advisory WARN band), the progress post-migration baseline, the gdd-mcp 27.7 tool-count + registry baselines
+  (12 -> 13), and skills.json (+2). Tarball golden 917 -> 934 (+17). The `lint:md` ignore was widened to nested
+  `node_modules`.
+
+---
+
 ## [1.51.0] - 2026-06-03
 
 ### Phase 51 - Instinct-Based Learnings

package/README.md

@@ -263,6 +263,8 @@ All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `ag
 
 **Instinct-based learnings (v1.51.0).** The reflection loop now produces atomic, confidence-weighted instinct units instead of prose nobody reads. Each unit (`reference/instinct-format.md`: trigger, confidence 0.3-0.9, domain, scope, project id) is stored via `scripts/lib/instinct-store.cjs` (a JSON store with optional `better-sqlite3` FTS5 acceleration, the same probe-and-fall-back pattern as cross-cycle recall, so no dependency is added). `design-reflector` dual-emits instincts plus a narrative; `/gdd:apply-reflections` accepts them; the decision-injector surfaces the top-3 relevant instincts into agent context on every design-file read; and `/gdd:instinct list|query|promote` inspects the project and global stores. A project instinct promotes to the global layer only after it recurs across at least two projects (a conservative `Beta(2,8)` prior keeps it advisory), and stale instincts decay and archive. **No new runtime dependency.**
 
+**Typed DesignContext graph (v1.52.0, keystone).** Design knowledge moves from flat `.design/map/*.md` notes to a typed graph at `.design/context-graph.json`: nodes are tokens, components, variants, states, motion fragments, a11y patterns, screens, layers, and design patterns; typed edges connect them (uses-token, composes, depends-on, consumes-context, and eight more). A Draft-07 schema (`reference/schemas/design-context.schema.json`) plus a dep-free validator (`scripts/validate-design-context.cjs`) and a pure query lib (`scripts/lib/design-context-query.cjs`: nodes / edges / path / consumers / unreachable / cycles / coverage) back it; regex extract passes build fragments that merge into the graph. The five mapper agents and the synthesizer dual-emit, so the markdown maps stay while fragments are added. A 13th read-only MCP tool (`gdd_context_query`) and two skills (`/gdd:context`, `/gdd:migrate-context`) expose it. Regex not tree-sitter, JSON not SQLite; this is the keystone for the phases that follow. **No new runtime dependency.**
+
 Verify with:
 
 ```

package/SKILL.md

@@ -113,6 +113,8 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `review-decisions [<id>] [--pending]` | `get-design-done:gdd-review-decisions` | Phase 40 - surface the async decision-review queue (`proposed → reviewing → approved → locked`); `--pending` shows decisions still awaiting action. Read-only |
 | `unlock-decision <id> --approver <who> [--reason <text>] [--dry-run]` | `get-design-done:gdd-unlock-decision` | Phase 40 - reopen a LOCKED decision (the only escape hatch); requires an approver + writes an audit entry; previews before writing |
 | `locale [<code>]` | `get-design-done:gdd-locale` | Phase 40.5 - inspect or set the GDD CLI locale (en/ru/uk/de/fr/zh/ja) for `--help`, errors, and skill prompt headers; missing keys fall back to English. No arg reports the resolved locale + coverage |
+| `context [nodes --type X \| edges --type Z \| path <a> <b> \| consumers-of <id> \| unreachable \| cycles \| coverage]` | `get-design-done:gdd-context` | Phase 52 - read-only query front end for the typed DesignContext graph at `.design/context-graph.json`; lists/filters nodes and edges, traces a path between two nodes, finds a node's consumers, and reports unreachable nodes, dependency cycles, and coverage. Never writes |
+| `migrate-context [--dry-run]` | `get-design-done:gdd-migrate-context` | Phase 52 - migrate a pre-Phase-52 project from flat `.design/map/*.md` mapper notes to the typed DesignContext graph; runs the extract-*.mjs passes, merges fragments, validates with `validate-design-context.cjs`, and flags low-confidence transforms for review. Preview-first; `--dry-run` previews without writing |
 
 ## Handoff Routing
 

package/agents/a11y-mapper.md

@@ -11,6 +11,7 @@ typical-duration-seconds: 45
 reads-only: false
 writes:
   - ".design/map/a11y.md"
+  - ".design/fragments/a11y-mapper.json"
 ---
 
 @reference/shared-preamble.md
@@ -136,9 +137,37 @@ Total: N findings. (0 = clean)
 ```
 ```
 
+## Graph fragment emission
+
+Dual-emit: keep writing `.design/map/a11y.md` above, and ALSO emit a typed graph fragment for the synthesizer to merge into `.design/context-graph.json`. Fragment shape and field rules come from `reference/design-context-schema.md`; allowed `tags[]` come from `reference/design-context-tag-vocab.md`. Do not invent fields or tags outside those two references.
+
+### 1. Deterministic phase (structural nodes/edges)
+
+Run the matching extractor over the same source roots you scanned above:
+
+```bash
+node scripts/lib/design-context/extract-a11y.mjs <source_root> [<source_root>...] > .design/fragments/a11y-mapper.json
+```
+
+`extract-a11y.mjs` walks the source roots with regex (zero-dep) and returns a Fragment whose `nodes[]` have `id`, `type` (`a11y-pattern`), and `name` filled, with stub `summary` you must replace. Patterns map to the ARIA, keyboard, focus, landmark, and skip-link signals you inventoried above. This is a static scan only; runtime behavior stays out (Phase 8).
+
+### 2. LLM phase (fill summary, tags, complexity)
+
+For every node the extractor produced, set:
+
+- `summary`: one sentence describing the pattern and the WCAG concern it touches, distinct from `name`. Example: "Focus-visible ring on interactive controls, supports 2.4.7".
+- `tags[]`: pick from `reference/design-context-tag-vocab.md` only (a11y terms such as `aria`, `keyboard`, `focus`, `landmark`, `contrast`). Where a node maps to a WCAG criterion you tracked, use the vocab tag for it. Drop any tag not in the vocab.
+- `complexity`: `simple` for a single attribute or landmark, `moderate` for a keyboard-handler pattern across a widget, `complex` for a composite pattern such as a focus-managed dialog.
+
+Add edges the extractor cannot infer: a pattern whose coverage a test asserts is `tested-by`; a pattern explained in a reference is `documented-by`. Set `direction` and `weight` per the schema.
+
+### 3. Write the fragment
+
+Write the completed Fragment to `.design/fragments/a11y-mapper.json` with `schema_version`, `mapper: "a11y-mapper"`, `generated_at` (ISO 8601), the enriched `nodes[]`, and `edges[]`. Resolve the main repo root the same way the rest of the pipeline does so a worktree run does not leak the file.
+
 ## Constraints
 
-No modifications outside `.design/map/`. No live browser. No git. No agent spawning.
+No modifications outside `.design/map/` and `.design/fragments/`. No live browser. No git. No agent spawning.
 
 ## A11Y MAP COMPLETE
 

package/agents/component-taxonomy-mapper.md

@@ -11,6 +11,7 @@ typical-duration-seconds: 45
 reads-only: false
 writes:
   - ".design/map/components.md"
+  - ".design/fragments/component-taxonomy-mapper.json"
 ---
 
 @reference/shared-preamble.md
@@ -81,9 +82,37 @@ dominant_styling: [CSS Modules | Tailwind | styled-components | mixed]
 |-----------|--------|
 ```
 
+## Graph fragment emission
+
+Dual-emit: keep writing `.design/map/components.md` above, and ALSO emit a typed graph fragment for the synthesizer to merge into `.design/context-graph.json`. Fragment shape and field rules come from `reference/design-context-schema.md`; allowed `tags[]` come from `reference/design-context-tag-vocab.md`. Do not invent fields or tags outside those two references.
+
+### 1. Deterministic phase (structural nodes/edges)
+
+Run the matching extractor over the same source roots you scanned above:
+
+```bash
+node scripts/lib/design-context/extract-components.mjs <source_root> [<source_root>...] > .design/fragments/component-taxonomy-mapper.json
+```
+
+`extract-components.mjs` walks the component files with regex (zero-dep) and returns a Fragment whose `nodes[]` have `id`, `type` (`component`, plus `variant` and `state` where detectable), and `name` filled, plus structural `composes` edges from import graphs. Each node `summary` arrives as a STUB you must replace.
+
+### 2. LLM phase (fill summary, tags, complexity)
+
+For every node the extractor produced, set:
+
+- `summary`: one sentence describing the component's responsibility, distinct from `name`. Example for `Card`: "Surface container that groups header, body, and action regions".
+- `tags[]`: pick from `reference/design-context-tag-vocab.md` only (for components, the atomic-design layer terms `atomic`, `molecular`, `organism`, `template`, plus role terms such as `interactive`, `layout`, `feedback`). Carry the atomic-design classification from your inventory into the matching layer tag. Drop any tag not in the vocab.
+- `complexity`: `simple` for an atom with no children, `moderate` for a molecule composing 2 to 5 children, `complex` for an organism with 6+ children or routable surface.
+
+Add cross-component edges the extractor cannot infer: a compound child specializing a base is `extends`; a near-duplicate sibling you flagged for reuse is `mirrors`. Set `direction` and `weight` per the schema.
+
+### 3. Write the fragment
+
+Write the completed Fragment to `.design/fragments/component-taxonomy-mapper.json` with `schema_version`, `mapper: "component-taxonomy-mapper"`, `generated_at` (ISO 8601), the enriched `nodes[]`, and `edges[]`. Resolve the main repo root the same way the rest of the pipeline does so a worktree run does not leak the file.
+
 ## Constraints
 
-Do not modify anything outside `.design/map/`. No git. No agent spawning.
+Do not modify anything outside `.design/map/` and `.design/fragments/`. No git. No agent spawning.
 
 ## Record
 

package/agents/design-debt-crawler.md

@@ -26,32 +26,23 @@ tree of an existing or legacy codebase, find design debt, group it by category,
 each finding by priority, and write a single project-scoped report at
 `.design/debt/DEBT-CATALOG.md`.
 
-You run once against the whole project, not against one cycle of work. This is the
-defining difference from `design-auditor`: that agent is cycle-scoped and reads the
-pipeline's recently completed work, while you ignore cycle state entirely and survey
-everything that exists on disk right now.
-
-You are a pure catalog. You do NOT modify source code, you do NOT apply fixes, and you
-do NOT spawn other agents. For every finding you suggest a remediation command the user
-can run later; you never run it yourself.
+You run once against the whole project, not one cycle of work (the defining difference
+from cycle-scoped `design-auditor`). You are a pure catalog: you do NOT modify source code,
+apply fixes, or spawn other agents. For every finding you suggest a remediation command the
+user can run later; you never run it yourself.
 
 ## CRITICAL: Project-Wide Scope, Not Cycle Scope
 
-**You do NOT read `.design/STATE.md` `<completed_tasks>`.** You do not scope to the
-current cycle, the current wave, or any recently touched file list. Your scope is the
-whole source tree.
+**You do NOT read `.design/STATE.md` `<completed_tasks>`.** You do not scope to the current
+cycle, wave, or any recently touched file list. Your scope is the whole source tree.
 
 - You **walk the entire codebase**, every source file under the configured source roots
-  (default `src/`), regardless of when it was last changed or whether any GDD cycle ever
-  touched it.
-- You write to a **project-scoped** path: `.design/debt/DEBT-CATALOG.md`. This is not a
-  cycle artifact and is not placed under any cycle directory.
-- You may read `.design/STATE.md` only to learn the `source_roots` value. You ignore its
-  `<completed_tasks>`, `<position>`, `wave`, and `cycle` fields for scoping. If STATE.md
-  is absent, default the source root to `src/` and proceed.
-
-If you ever find yourself filtering files by a completed-task list, stop: that is the
-cycle-scoped behavior this agent exists to avoid.
+  (default `src/`), regardless of when it last changed or whether a GDD cycle touched it.
+- You write to one **project-scoped** path, `.design/debt/DEBT-CATALOG.md`, never under a cycle.
+- You may read `.design/STATE.md` solely for `source_roots`; ignore its `<completed_tasks>`,
+  `<position>`, `wave`, and `cycle` fields. If STATE.md is absent, default to `src/`.
+- If you ever find yourself filtering files by a completed-task list, stop: that is the
+  cycle-scoped behavior this agent exists to avoid.
 
 ## Required Reading
 
@@ -63,14 +54,36 @@ listed file before acting. Minimum expected files:
 - @reference/anti-slop-rubric.md
 - @reference/reviewer-confidence-gate.md
 
-`reference/debt-categories.md` is the taxonomy you classify against and the source of
-the priority-scoring model. `reference/anti-patterns.md` is the BAN-NN and SLOP-NN
-catalog that the anti-pattern class cross-references.
+`reference/debt-categories.md` is the taxonomy and the source of the priority-scoring model.
+`reference/anti-patterns.md` is the BAN-NN and SLOP-NN catalog the anti-pattern class cites.
 
 ---
 
 ## Work
 
+### Step 0: Mode selection (graph-aware dual-mode)
+
+Check for the typed DesignContext graph at `.design/context-graph.json`. When it exists,
+PREFER graph queries via `scripts/lib/design-context-query.cjs` for the three classes that
+map cleanly, and grep for the rest. When it is absent, run the full grep scan (Step 2) as
+before. Queries (`Q="node ${CLAUDE_PLUGIN_ROOT:-.}/scripts/lib/design-context-query.cjs"`,
+all with `--file .design/context-graph.json --json`):
+
+```bash
+$Q nodes --type component        # untokenized: a component id NOT in any uses-token source
+$Q edges --type uses-token       #   ...the tokenized component ids
+$Q nodes --type anti-pattern     # anti-pattern: each node is a direct finding
+$Q edges --type conflicts-with   #   ...names the sanctioned pattern it collides with
+$Q nodes                         # complexity outliers: keep complexity === "complex"
+```
+
+A graph hit cites the node `id` as the location and the query as the evidence. The other six
+classes (color-literal, contrast, density-spacing, typography-drift, a11y-text,
+aesthetic-slop) always grep, since the graph lacks their raw `file:line` literal evidence.
+The output contract, the confidence gate (Step 2.5), and the priority scoring (Step 3) are
+identical in both modes: a graph-sourced finding still clears the Pre-Report Gate and carries
+a `confidence` value and a `priority` score.
+
 ### Step 1: Determine source roots
 
 Read `source_roots` from `.design/STATE.md` if present; otherwise default to `src/`.
@@ -83,8 +96,9 @@ find src/ -type f \( -name "*.tsx" -o -name "*.jsx" -o -name "*.ts" -o -name "*.
 
 ### Step 2: Scan each debt class
 
-Run one pass per class from `reference/debt-categories.md`. Record `file:line` plus the
-matched text for every hit so each catalog row is traceable.
+Run one pass per class from `reference/debt-categories.md`, recording `file:line` plus the
+matched text for traceability. When a graph exists (Step 0), the anti-pattern,
+untokenized-component, and complexity-outlier passes below are the no-graph fallback.
 
 **color-literal** (raw color values, not token references):
 
@@ -93,38 +107,31 @@ grep -rEn "#[0-9a-fA-F]{3,8}|rgb\(|rgba\(|hsl\(|hsla\(" src/ \
   --include="*.tsx" --include="*.jsx" --include="*.css" --include="*.scss" 2>/dev/null
 ```
 
-Exclude the palette or token-definition file (a literal inside a `var(--x: #hex)`
-definition IS the token). Count distinct literals and total occurrences.
+Exclude the token-definition file (a literal inside a `var(--x: #hex)` definition IS the
+token). Count distinct literals and total occurrences.
 
-**anti-pattern** (BAN-NN and SLOP-NN): run the deterministic detector once over the
-tree. It returns every statically matchable rule in one pass with `file`, `line`,
-`ruleId`, and a reference link, offline and with zero model calls.
+**anti-pattern** (BAN-NN and SLOP-NN): run the deterministic detector once over the tree.
+It returns every statically matchable rule with `file`, `line`, `ruleId`, and a reference
+link, offline.
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT:-.}/bin/gdd-detect" src/ --json 2>/dev/null || true
 ```
 
-Parse the JSON `findings` array. The detector cannot match the two subjective rules
-(BAN-04 keyboard-action animation, BAN-10 nested equal radius); list those as a
-manual-review note rather than counting them.
+Parse the JSON `findings` array. The detector cannot match the two subjective rules (BAN-04
+keyboard-action animation, BAN-10 nested equal radius); list those as a manual-review note.
 
 **untokenized-component** (component renders surface without token references):
 
 ```bash
-# arbitrary bracket values + inline hex inside component files
 grep -rEn "\[[0-9]+px\]|\[#[0-9a-fA-F]{3,8}\]" src/ \
   --include="*.tsx" --include="*.jsx" --include="*.vue" --include="*.svelte" 2>/dev/null
-# token references present in the same file set (for the ratio)
-grep -rEln "var\(--|theme\(" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null
+grep -rEln "var\(--|theme\(" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null   # tokenized files
 ```
 
-A component file with literal or bracket hits and no `var(--` reference is untokenized.
-The literal-to-token ratio per file is the strength signal.
+A component file with literal or bracket hits and no `var(--` reference is untokenized; the per-file literal-to-token ratio is the strength signal.
 
-**contrast** (foreground and background pairs below WCAG AA): resolve color pairs that
-share an element or selector, compute the ratio, and flag pairs under 4.5:1 for body
-text or 3:1 for large text and non-text indicators. Pairs built from unresolvable
-runtime values become a manual-review note.
+**contrast** (foreground and background pairs below WCAG AA): resolve color pairs sharing an element or selector, compute the ratio, and flag pairs under 4.5:1 for body text or 3:1 for large text and non-text indicators. Unresolvable runtime pairs become a manual-review note.
 
 **density-spacing** (off-scale spacing and inconsistent rhythm):
 
@@ -133,8 +140,7 @@ grep -rEon "(p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap|space-[xy])-[0-9.]+" sr
   --include="*.tsx" --include="*.jsx" 2>/dev/null | sort | uniq -c | sort -rn
 ```
 
-Flag values that are not on the project's modular scale (default 4 / 8 / 12 / 16 / 24 /
-32) and clusters where sibling components use different step counts for one role.
+Flag values off the modular scale (default 4 / 8 / 12 / 16 / 24 / 32) and sibling clusters with mismatched step counts.
 
 **typography-drift** (off-scale sizes, too many families, weak weight hierarchy):
 
@@ -145,8 +151,7 @@ grep -rEon "text-[a-z0-9]+|font-(bold|semibold|medium|normal|light)|font-size:[^
 grep -rEn "font-family:|fontFamily" src/ --include="*.css" --include="*.ts" 2>/dev/null
 ```
 
-Flag a long tail of one-off sizes, more than two families, and `font-weight` under 400
-on small text.
+Flag a long tail of one-off sizes, more than two families, and `font-weight` under 400 on small text.
 
 **a11y-text** (text-content accessibility debt):
 
@@ -156,14 +161,13 @@ grep -rEn "No data|No results|Nothing here|went wrong|error occurred" src/ \
   --include="*.tsx" --include="*.jsx" 2>/dev/null
 ```
 
-Flag meaningful images without `alt`, icon-only controls without an accessible name,
-placeholder used as the only label, and generic empty or error copy.
+Flag meaningful images without `alt`, icon-only controls without an accessible name, placeholder-as-only-label, and generic empty or error copy.
 
-**aesthetic-slop** (generically AI-default even when pillars pass): the orthogonal
-verb-axis class from `reference/anti-slop-rubric.md`. `agents/design-auditor.md` scores
-five axes (Directness, Distinctness, Hierarchy, Authenticity, Density, 1-10 each) and routes
-any finding summing below 35 of 50 here as `category: aesthetic-slop`, carrying its
-`verb_axes_scored` values plus matched `reference/visual-tells.md` categories as evidence.
+**aesthetic-slop** (generically AI-default even when pillars pass): the orthogonal verb-axis
+class from `reference/anti-slop-rubric.md`. `agents/design-auditor.md` scores five axes
+(Directness, Distinctness, Hierarchy, Authenticity, Density, 1-10 each) and routes any finding
+summing below 35 of 50 here as `category: aesthetic-slop`, carrying its `verb_axes_scored`
+values plus matched `reference/visual-tells.md` categories as evidence.
 
 ### Step 2.5: Pre-Report Gate + confidence
 
@@ -192,12 +196,8 @@ Sort the catalog by `priority` descending. Break ties by visible-delta, then pre
 
 ### Step 4: Write the catalog
 
-Create the directory and write the report. Each row suggests a remediation command per
-the ROADMAP open-question default: pure catalog, no auto-fix.
-
-```bash
-mkdir -p .design/debt
-```
+Create the directory (`mkdir -p .design/debt`) and write the report. Each row suggests a
+remediation command per the ROADMAP open-question default: pure catalog, no auto-fix.
 
 ---
 

package/agents/design-research-synthesizer.md

@@ -11,6 +11,7 @@ typical-duration-seconds: 60
 reads-only: false
 writes:
   - ".design/DESIGN-CONTEXT.md"
+  - ".design/context-graph.json"
 ---
 
 @reference/shared-preamble.md
@@ -26,6 +27,7 @@ Aggregates outputs from the 5 mappers, discussant decisions, phase-researcher fi
 - `.design/map/visual-hierarchy.md` - visual-hierarchy-mapper output
 - `.design/map/a11y.md` - a11y-mapper output
 - `.design/map/motion.md` - motion-mapper output
+- `.design/fragments/*.json` - the typed graph fragments the 5 mappers dual-emit (one per mapper); these feed the graph merge below
 - `.design/STATE.md` - `<decisions>` block (D-XX entries) and `<connections>` block
 - Any phase-researcher output provided in the spawn prompt `<research>` block
 - Pinterest MCP (if `pinterest: available` in STATE.md `<connections>`) - use `pinterest_search` for design inspiration queries; results appended to `<connection_sources>` in DESIGN-CONTEXT.md
@@ -85,6 +87,30 @@ Use Glob to confirm presence; skip absent files gracefully and mark section as `
    ---
    ```
 
+## Graph merge and validation
+
+The 5 mappers now dual-emit typed graph fragments to `.design/fragments/<mapper>.json` alongside their `.design/map/*.md`. After they finish, merge those fragments into the typed DesignContext graph, validate it, and derive the human view from it. This runs in addition to the markdown synthesis above (dual-emit, kept for one minor for backward-compat).
+
+1. **Merge fragments into the graph.** Invoke the merge engine over every fragment present:
+
+   ```bash
+   node scripts/lib/design-context/merge-fragments.mjs .design/fragments/*.json > .design/context-graph.json 2> .design/fragments/merge.stderr
+   ```
+
+   `merge-fragments.mjs` dedupes nodes by `id`, recovers or drops dangling edges, and emits the merged Graph (`schema_version`, `generated_at`, `nodes[]`, `edges[]`) per `reference/design-context-schema.md`. Items it could not auto-fix (dropped edges, id collisions it could not reconcile) are written to stderr; keep that stderr for the review pass below.
+
+2. **Validate the graph (hard block).** Run the validator and gate on its exit code:
+
+   ```bash
+   node scripts/validate-design-context.cjs .design/context-graph.json
+   ```
+
+   Exit 0 is clean. A non-zero exit is a hard block: do NOT write a `status: complete` DESIGN-CONTEXT.md over a graph that failed validation. Report the validator output and stop, leaving the prior artifact in place. Soft warnings (for example a `summary` equal to its `name`, or a tag near the vocab boundary) are surfaced but do not block.
+
+3. **Derive the human view FROM the graph.** Treat `.design/context-graph.json` as the source of truth and render `.design/DESIGN-CONTEXT.md` as an auto-derived view of it. Keep the existing section structure so downstream consumers do not break: `<token_system>` from `token` nodes, `<component_inventory>` from `component`/`variant`/`state` nodes grouped by atomic-design layer tag, `<visual_hierarchy>` from `screen`/`pattern`/`anti-pattern` nodes, `<a11y_baseline>` from `a11y-pattern` nodes, `<motion_system>` from `motion-fragment` nodes, and `<decisions>` from STATE.md as before. Each node's `summary` and `tags[]` populate the rows; edges populate the cross-reference notes (for example which components consume which tokens via `uses-token`).
+
+4. **Review pass for could-not-fix items.** Hand the contents of `.design/fragments/merge.stderr` (plus any validator soft-warnings) to an assemble-review pass that cites the offending pattern and proposes a fix back to the owning mapper. Follow the assemble-reviewer pattern used elsewhere in the pipeline for "could not fix" hand-off. A dedicated `assemble-reviewer` agent is a likely future addition for this; do not create or spawn it here. For now, list these items under a `<graph_review>` section in DESIGN-CONTEXT.md so the next cycle can act on them.
+
 ## Handoff mode
 
 Handoff mode activates when `handoff_source` is present in `.design/STATE.md <position>`. In this mode, the synthesizer's primary input is the Claude Design handoff bundle rather than the 5 mapper outputs.
@@ -163,7 +189,7 @@ Read .design/STATE.md
 
 Before writing any `.design/` artifact, resolve the main repo root via `scripts/lib/worktree-resolve.cjs` (`resolveDesignRoot`) so a worktree run writes to the main checkout and does not leak.
 
-Single file: `.design/DESIGN-CONTEXT.md`.
+Two artifacts (dual-emit): `.design/context-graph.json` (the merged, validated typed graph, source of truth) and `.design/DESIGN-CONTEXT.md` (the auto-derived human view of that graph).
 
 ## Record
 

package/agents/motion-mapper.md

@@ -11,6 +11,7 @@ typical-duration-seconds: 30
 reads-only: false
 writes:
   - ".design/map/motion.md"
+  - ".design/fragments/motion-mapper.json"
 ---
 
 @reference/shared-preamble.md
@@ -25,9 +26,7 @@ You inventory motion and animation patterns. Zero session memory. You do not mod
 
 - `.design/STATE.md`
 - `reference/motion.md` (if present) - **the motion domain-index (Phase 45): start here.** It indexes the
-  motion fragments below with a "use this when" pointer for each. Load a specific fragment ONLY when you
-  reach the classification step that needs it (drill-in), not all of them up front - this is the bulk of
-  the token saving (the index is ~1.7k tokens vs ~15k for all four fragments).
+  motion fragments below with a "use this when" pointer for each. Load a specific fragment ONLY when you reach the classification step that needs it (drill-in), not all of them up front.
 - Drill-in fragments (load on demand, per the index in `motion.md`):
   - `reference/motion-advanced.md` - advanced patterns: spring physics, scroll-driven, FLIP, View Transitions API, gesture/drag mechanics, clip-path patterns, blur crossfades, Framer Motion hardware-accel gotcha
   - `reference/motion-easings.md` - 12 canonical easing presets; classify each detected easing against this catalog
@@ -91,10 +90,7 @@ grep -rEn "animation-timeline|ScrollTimeline|useScroll\b" src/ | head -30
 grep -rEn "\.animate\(\[|WebAnimation|getAnimations" src/ | head -20
 ```
 
-Classify gesture patterns against `reference/motion-advanced.md` (velocity formula, pointer capture, multi-touch protection).
-Classify easing values against the 12 canonical presets in `reference/motion-easings.md`; output `"custom"` with justification for anything that doesn't match.
-Classify page/route transitions against the 8 families in `reference/motion-transition-taxonomy.md`.
-Classify spring configs against the 4 presets in `reference/motion-spring.md`.
+Classify gesture patterns against `reference/motion-advanced.md` (velocity formula, pointer capture, multi-touch protection), easing values against the 12 presets in `reference/motion-easings.md` (output `"custom"` with justification for anything unmatched), page/route transitions against the 8 families in `reference/motion-transition-taxonomy.md`, and spring configs against the 4 presets in `reference/motion-spring.md`.
 
 ## Output Format - `.design/map/motion.md`
 
@@ -134,10 +130,12 @@ generated: [ISO 8601]
 ```
 
 ## CSS transitions
+
 | File | Property | Duration | Easing | Canonical Easing |
 |------|----------|----------|--------|-----------------|
 
 ## Library usage
+
 | Library | Files | Notes |
 |---------|-------|-------|
 
@@ -149,20 +147,20 @@ generated: [ISO 8601]
 - Narrative (>800ms): [N]
 
 ## Easing classification
+
 | Detected Easing | Canonical Name | Count | Notes |
 |----------------|---------------|-------|-------|
 
 ## Advanced patterns detected
+
 | Pattern | Files | Notes |
 |---------|-------|-------|
 
 ## Reduced-motion compliance
-- `prefers-reduced-motion` queries present: [N]
-- Animated components lacking a reduced-motion branch: [list]
+- `prefers-reduced-motion` queries present: [N]; animated components lacking a reduced-motion branch: [list]
 
 ## Score
-Reduced-motion compliance: [Full | Partial | None]
-Motion consistency: [Consistent | Mixed | Chaotic]
+Reduced-motion compliance: [Full | Partial | None]. Motion consistency: [Consistent | Mixed | Chaotic]
 
 ## Micro-motion findings
 
@@ -207,12 +205,36 @@ After the standard motion inventory, emit a "Micro-motion findings" section with
 Total: N violations found. (0 = clean)
 ```
 
-If no violations found, emit: `## Micro-motion findings — CLEAN (0 violations)`
+If no violations found, emit: `## Micro-motion findings (CLEAN, 0 violations)`
+```
+
+## Graph fragment emission
+
+Dual-emit: keep writing `.design/map/motion.md` above, and ALSO emit a typed graph fragment for the synthesizer to merge into `.design/context-graph.json`. Fragment shape comes from `reference/design-context-schema.md`; allowed `tags[]` come from `reference/design-context-tag-vocab.md`. Do not invent fields or tags outside those references.
+
+### 1. Deterministic phase
+
+```bash
+node scripts/lib/design-context/extract-motion.mjs <source_root> [<source_root>...] > .design/fragments/motion-mapper.json
 ```
 
+`extract-motion.mjs` walks the source roots with regex (zero-dep) and returns a Fragment whose `nodes[]` (`type: motion-fragment`) have `id`, `name`, and a stub `summary` you replace. It maps to the `animations[]` you already inventoried, so reuse that data.
+
+### 2. LLM phase (fill summary, tags, complexity)
+
+- `summary`: one sentence per node, distinct from `name`. Example: "Toast enter, opacity plus translateY over 180ms".
+- `tags[]`: from the tag-vocab only (motion terms such as `enter`, `exit`, `gesture`, `scroll-driven`, `reduced-motion`). Drop tags not in the vocab.
+- `complexity`: `simple` for a single CSS transition, `moderate` for a library spring or multi-property tween, `complex` for FLIP, scroll-driven, or gesture-physics patterns.
+
+Add `transitions-to` edges between fragments that form an enter/exit pair or a route sequence. Set `direction` and `weight` per the schema.
+
+### 3. Write the fragment
+
+Write the Fragment to `.design/fragments/motion-mapper.json` (`schema_version`, `mapper: "motion-mapper"`, `generated_at` ISO 8601, enriched `nodes[]`, `edges[]`), resolving the main repo root so a worktree run does not leak the file.
+
 ## Constraints
 
-No modifications outside `.design/map/`. No git. No agent spawning.
+No modifications outside `.design/map/` and `.design/fragments/`. No git. No agent spawning.
 
 ## Record
 

package/agents/token-mapper.md

@@ -11,6 +11,7 @@ typical-duration-seconds: 45
 reads-only: false
 writes:
   - ".design/map/tokens.md"
+  - ".design/fragments/token-mapper.json"
 ---
 
 @reference/shared-preamble.md
@@ -140,9 +141,37 @@ Total: N findings. (0 = clean)
 ```
 ```
 
+## Graph fragment emission
+
+Dual-emit: keep writing `.design/map/tokens.md` above, and ALSO emit a typed graph fragment so the synthesizer can merge it into `.design/context-graph.json`. Fragment shape and field rules come from `reference/design-context-schema.md`; the allowed `tags[]` come from `reference/design-context-tag-vocab.md`. Do not invent fields or tags outside those two references.
+
+### 1. Deterministic phase (structural nodes/edges)
+
+Run the matching extractor over the same `<source_roots>` you scanned above:
+
+```bash
+node scripts/lib/design-context/extract-tokens.mjs <source_root> [<source_root>...] > .design/fragments/token-mapper.json
+```
+
+`extract-tokens.mjs` walks the source roots with regex (zero-dep) and returns a Fragment whose `nodes[]` have `id`, `type` (`token`, subtype color/spacing/typography/radius/shadow), and `name` filled, plus structural `uses-token` edges from consuming files. Each node `summary` arrives as a STUB you must replace.
+
+### 2. LLM phase (fill summary, tags, complexity)
+
+For every node the extractor produced, set:
+
+- `summary`: one sentence describing the token's role, distinct from `name` (a summary equal to the name is a soft-warn in the validator). Example for `--color-primary`: "Brand accent used for primary CTAs and active states".
+- `tags[]`: pick from `reference/design-context-tag-vocab.md` only (for tokens, terms such as `color`, `spacing`, `typography`, `semantic`, `brand`). Drop any tag not in the vocab.
+- `complexity`: `simple` for a single literal value, `moderate` for a token that aliases or composes others (for example a shadow built from a 3-layer formula), `complex` for a token whose value depends on mode/theme resolution.
+
+Add cross-token edges you can see that the extractor cannot infer: a semantic token aliasing a primitive is `extends`; a shadow token referencing spacing or color primitives is `uses-token`. Set `direction` and `weight` per the schema.
+
+### 3. Write the fragment
+
+Write the completed Fragment to `.design/fragments/token-mapper.json` with `schema_version`, `mapper: "token-mapper"`, `generated_at` (ISO 8601), the enriched `nodes[]`, and `edges[]`. Resolve the main repo root the same way the rest of the pipeline does so a worktree run does not leak the file.
+
 ## Constraints
 
-You MUST NOT modify anything outside `.design/map/`. Do not run git commands or spawn agents.
+You MUST NOT modify anything outside `.design/map/` and `.design/fragments/`. Do not run git commands or spawn agents.
 
 ## Record