@hegemonart/get-design-done 1.50.1 → 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.50.1"
+    "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.50.1",
+      "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.50.1",
+  "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,99 @@ 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
+
+GDD's reflection loop was extractive, not predictive: `/gdd:extract-learnings` wrote a prose `LEARNINGS.md` that no
+downstream agent read. Phase 51 restructures learnings into atomic, confidence-weighted instinct units that are
+queryable, deduplicable, promotable, and surfaced back into agent context. Adapted from ecc's continuous-learning v2
+(project-vs-global scope). Planned and executed via the GSD pipeline (3 parallel executor subagents). No new runtime
+dependency, no new egress.
+
+### Breaking changes
+
+- **Reflection output gains atomic instinct units.** `design-reflector` now emits a `## Atomic instincts` section
+  (YAML units per `reference/instinct-format.md`) alongside a `## Narrative reflection` (dual-emit for one minor
+  version), and `/gdd:apply-reflections` gains an `[INSTINCT]` proposal class (accept/reject/defer/edit). Consumers of
+  the reflection format should read both sections.
+- **A new instinct store + schema.** `scripts/lib/instinct-store.cjs` is the source of truth (`.design/instincts/instincts.json`
+  project + `~/.claude/gdd/global-instincts.json` global); `reference/schemas/instinct.schema.json` is wired into
+  `validate:schemas` and enforces the unit shape (confidence 0.3-0.9, domain enum, scope, sha8 project_id).
+
+### Added
+
+- **`reference/instinct-format.md`** + **`reference/schemas/instinct.schema.json`**: the atomic instinct unit (YAML
+  frontmatter `id`/`trigger`/`confidence`/`domain`/`scope`/`project_id`/`source`/`cycles_seen`/`first_seen`/`last_seen`
+  with a prose body), the K=2/M=2 promotion gate, the Beta(2,8) prior, and TTL decay.
+- **`scripts/lib/instinct-store.cjs`**: JSON-canonical store with OPTIONAL FTS5 acceleration via
+  `probeOptional('better-sqlite3')` (the Phase 19.5 design-search pattern, so no dependency is added). Exports
+  `add`/`list`/`query`/`get`/`promote`/`touch`/`decay`/`deriveProjectId`; atomic writes; worktree-safe.
+- **`/gdd:instinct`** skill: `list` / `query "<keyword>"` (FTS5 or in-memory scan) / `promote <id>` (project to global,
+  gated on `cycles_seen >= 2` across `>= 2` distinct project ids; user-confirmed).
+- **Decision-injector integration**: `gdd-decision-injector.js` surfaces a top-3 `## Relevant instincts` block in
+  agent context (non-fatal; skipped when no store is present).
+- **TTL decay**: instincts not surfaced in 6 cycles decay (`confidence *= 0.9`); below 0.2 they archive. Wired into the
+  cleanup sweep. Three `instinct_*` event types seeded into `events.schema.json`. `extract-learnings` dual-emits.
+
+### Notes
+
+- 6-manifest lockstep at **v1.51.0** + `OFF_CADENCE_VERSIONS.add('1.51.0')` + 37 `manifests-version.txt` baselines.
+  Re-locked: skill-list (89), registry (176), phase-42 count (113), the events-schema sha256 snapshot,
+  resilience-primitives (40, +instinct-store.cjs), the phase-28.5 distribution + warn count (5 -> 8; apply-reflections
+  was trimmed back to <=110), skill-graph regenerated. Tarball golden 912 -> 917 (+5; the cleanup/injector/schema edits
+  are same-path).
+- Out of scope: cross-project federation, auto-skill-generation from instincts, embedding-based clustering, cross-runtime sync.
+
+---
+
 ## [1.50.1] - 2026-06-03
 
 ### Fixed

package/README.md

@@ -261,6 +261,10 @@ All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `ag
 
 **Authoring contract v3 (v1.50.0).** Two additions. A verb-based anti-slop rubric (`reference/anti-slop-rubric.md`) scores five orthogonal axes (Directness, Distinctness, Hierarchy, Authenticity, Density); a sum below 35/50 routes a finding to the debt crawler as `aesthetic-slop`. It rides as a lens-tag on the existing 7-pillar audit, so it catches "generically AI-default" where the pillars catch "wrong". And a machine-parseable skill-composition manifest: optional `composes_with` / `next_skills` frontmatter, a DAG validator (`validate:composition-graph` fails on cycles or dangling refs), and an auto-generated `reference/skill-graph.md`. Skill descriptions move to a multi-paragraph v3 form (`<what>. Use when <triggers>. Activates for requests involving <kw>.`) with both forms accepted during a transition window, a boilerplate-cohort lint, and a `/gdd:new-skill` scaffolder. **No new runtime dependency.**
 
+**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

@@ -2,7 +2,7 @@
 name: get-design-done
 short_name: gdd
 description: "Master design pipeline for Claude Code. 5-stage workflow: Brief → Explore → Plan → Design → Verify. Run 'brief' first in any new project to capture the design problem, then 'explore' to inventory the codebase and interview for context. Invoke without arguments for status and auto-routing."
-argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|live|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|pin|unpin|list-pins|new-skill|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
+argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|live|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|pin|unpin|list-pins|new-skill|instinct|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
 user-invocable: true
 ---
 
@@ -94,6 +94,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `unpin <skill>` | `get-design-done:gdd-unpin` | Phase 46 - remove pinned aliases for a skill (only files carrying the gdd-pinned-skill marker) |
 | `list-pins` | `get-design-done:gdd-list-pins` | Phase 46 - show pinned aliases per harness with their source skill and last-pinned timestamp |
 | `new-skill <name>` | `get-design-done:gdd-new-skill` | Phase 50 - interactive scaffolder for a new Phase 28.5 + v3-compliant skill (multi-paragraph description, lifecycle stage, optional composes_with); writes source/skills/<name>/SKILL.md |
+| `instinct [list\|query <kw>\|promote <id>]` | `get-design-done:gdd-instinct` | Phase 51 - inspect and manage atomic instinct learning units (project + global stores); list, search by keyword, or promote a vetted project instinct to global once it clears the cross-project gate |
 | `quality-gate` | `get-design-done:quality-gate` | Phase 25 - parallel lint/type/test/visual command runner; classifies failures via quality-gate-runner agent |
 | `turn-closeout` | `get-design-done:turn-closeout` | Phase 25 - Stop-hook mirror skill; finalizes per-turn STATE blocks and emits closeout events |
 | `bandit-status` | `get-design-done:bandit-status` | Phase 27.5 - read-only diagnostic surface for the bandit posterior; per-(agent, bin, delegate, tier) snapshots (alpha, beta, mean, stddev, count, last-used). Use `/gdd:bandit-reset` to mutate. |
@@ -112,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-reflector.md

@@ -257,6 +257,39 @@ Append stdout to the cycle markdown body (after Section 8 / before the Proposals
 
 ---
 
+## Atomic instincts
+
+Phase 51 adds atomic instinct units alongside the prose reflection. For each pattern you observed this cycle that is small enough to state as a single trigger plus a one-line response, emit a structured instinct unit. The narrative below stays for human reading; this section is the machine-readable twin. Both are emitted for one minor version so readers and tooling migrate together.
+
+Emit 0 to N units. Each unit follows `reference/instinct-format.md` exactly: YAML frontmatter (`id`, `trigger`, `confidence` from 0.3 to 0.9, `domain` from the format's enum, `scope`, `project_id`, `source`, `cycles_seen`, `first_seen`, `last_seen`) plus a short body. Set `source: design-reflector`. Set `confidence` from the strength of the evidence - a pattern seen once this cycle stays near 0.3 to 0.5; a pattern that recurs across prior learnings earns more. Do not exceed 0.9.
+
+A unit is a proposal, not a stored fact. You write the units here; the user accepts them via `{{command_prefix}}apply-reflections` (the `[INSTINCT]` class). Accepted units land in the store through `scripts/lib/instinct-store.cjs` `add(unit, { scope, baseDir })` at the emitted confidence. You never call `add()` yourself and you never write to `.design/instincts/instincts.json` directly.
+
+Emit each unit in a fenced `yaml` block so the apply step can parse it:
+
+```yaml
+id: in-<short-hash>
+trigger: <one-line condition that should fire this instinct>
+confidence: 0.45
+domain: <enum value from reference/instinct-format.md>
+scope: project
+project_id: <project id from STATE.md or deriveProjectId>
+source: design-reflector
+cycles_seen: 1
+first_seen: <ISO-8601>
+last_seen: <ISO-8601>
+---
+<one or two sentences: the response this instinct recommends and why>
+```
+
+If no pattern this cycle is atomic enough to state as a single trigger, write one line: "No atomic instincts this cycle." and move on. Do not pad.
+
+### Narrative reflection
+
+Keep the prose reflection for human readers. Summarize, in two to four sentences, the through-line of this cycle: what kept recurring, what shifted, and which instinct units above you have the most confidence in. This subsection is what a person skims; the units above are what tooling consumes.
+
+---
+
 ## Proposals
 
 After all sections, write a **Proposals** section. Number proposals sequentially. Every proposal must include evidence - no vague observations.

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