@hegemonart/get-design-done 1.51.0 → 1.53.0

package/dist/claude-code/.claude/skills/migrate-context/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: gdd-migrate-context
+description: "Migrates a pre-Phase-52 project from the flat .design/map/*.md mapper notes to the typed DesignContext graph at .design/context-graph.json. Reads the old map notes, runs the deterministic extract-*.mjs passes to build mapper fragments, merges them with merge-fragments.mjs, validates the result with validate-design-context.cjs, and flags every low-confidence transform for human review before anything is trusted. Read-first and reversible; --dry-run previews the plan without writing. Use when upgrading a project to the DesignContext graph and .design/map/*.md still holds the only structured design notes. Activates for requests involving migrating design maps, building the context graph from old notes, or DesignContext graph migration."
+argument-hint: "[--dry-run]"
+tools: Read, Write, Bash
+user-invocable: true
+---
+
+# /gdd:migrate-context
+
+Closes the pre-graph gap: before Phase 52 a project recorded its structured design knowledge as flat
+`.design/map/*.md` mapper notes (token map, component taxonomy, motion map, a11y map, visual-hierarchy
+map). Phase 52 introduced the typed DesignContext graph at `.design/context-graph.json`. This skill
+carries a project across that boundary: it reads the old map notes, rebuilds the graph deterministically
+from source, validates it, and surfaces anything it could not transform with confidence so a human can
+confirm it. It never trusts a low-confidence guess silently.
+
+Contracts: `../../reference/design-context-schema.md` (the Node / Edge / Fragment / Graph shapes) and
+`../../reference/design-context-tag-vocab.md` (the controlled `tags[]` vocabulary).
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `/gdd:migrate-context` | Run the full migration: read old maps, extract fragments, merge, validate, then report the low-confidence items for review. |
+| `/gdd:migrate-context --dry-run` | Preview only. Print the migration plan and what each step would write, change nothing on disk. |
+
+## Step 1 - Detect the pre-52 state
+
+Read the project layout before touching anything.
+
+1. List `.design/map/*.md`. These are the pre-52 mapper notes (for example `token-map.md`,
+   `component-taxonomy.md`, `motion-map.md`, `a11y-map.md`, `visual-hierarchy.md`). If the directory is
+   absent or empty, there is nothing to migrate: print `No .design/map/*.md notes found; nothing to
+   migrate.` and stop.
+2. Check whether `.design/context-graph.json` already exists. If it does, this is a re-run: keep the
+   existing graph as a backup reference and report that the migration will rebuild it. Do not delete it.
+3. In `--dry-run`, print the file list and the planned outputs (`.design/fragments/<mapper>.json` per
+   mapper, then `.design/context-graph.json`) and stop before Step 2.
+
+## Step 2 - Rebuild fragments deterministically
+
+The graph topology comes from the source tree, not from prose. Run each deterministic extractor over the
+configured source roots (default `src/`; read `source_roots` from `.design/STATE.md` if present). Each
+extractor is pure, dependency-free, and prints a schema-valid Fragment to stdout.
+
+```bash
+mkdir -p .design/fragments
+for mapper in tokens components motion a11y visual-hierarchy; do
+  node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/lib/design-context/extract-${mapper}.mjs" src/ \
+    > ".design/fragments/extract-${mapper}.json"
+done
+```
+
+The extractors fill `id / type / name / subtype / tags / complexity` and every edge they can prove; they
+leave each node `summary` empty for the summary pass. Use the old `.design/map/*.md` notes as the source
+of the human-authored `summary` text and any tags the extractor could not infer: for each node whose name
+matches a map entry, copy that note's one-line description into the node `summary` and add any vocabulary
+tags it implies. This is the only place prose feeds the graph.
+
+## Step 3 - Merge into the canonical graph
+
+Merge the fragments into the single graph. The merger dedupes nodes by `id`, unions tags, prefers a
+non-stub summary over the empty stub, and keeps an edge only when both endpoints resolve to a node in some
+fragment. Dropped dangling edges are reported on stderr as `could-not-fix:` lines.
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/lib/design-context/merge-fragments.mjs" \
+  .design/fragments --out .design/context-graph.json
+```
+
+Capture the stderr `could-not-fix:` lines. Each one is a transform the merge could not complete (a map
+note referenced an entity the extractor never found in source). These are low-confidence items for Step 5,
+not silent drops.
+
+## Step 4 - Validate
+
+Validate the merged graph. The validator checks structure, referential integrity (no dangling edges),
+unique ids, non-stub summaries (soft warning), and the controlled tag vocabulary (soft warning).
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/validate-design-context.cjs" .design/context-graph.json
+```
+
+Exit `0` is clean, `1` is warnings only (stub summaries or unknown tags to tidy later), `2` is a hard
+error (a dangling edge or duplicate id) that must be fixed before the graph is trusted. On exit `2`, do
+not present the graph as migrated: report the errors and stop so a human can resolve them.
+
+## Step 5 - Flag low-confidence transforms
+
+Collect everything that needs human eyes and present it as one review list rather than applying it:
+
+- every `could-not-fix:` line from the merge (an unresolved or dropped edge);
+- every node still carrying an empty `summary` after Step 2 (a map note had no matching entity, or no
+  note existed);
+- every validator `WARN` (stub summary, tag outside the controlled vocabulary).
+
+Print the list with a clear heading and ask the user to confirm or correct each item. Do not auto-resolve
+a low-confidence transform: a wrong edge or a mislabeled node poisons every later graph query.
+
+## Step 6 - Deprecate the old map notes
+
+The flat `.design/map/*.md` notes stay readable for one minor version so nothing breaks mid-upgrade. Add a
+one-line deprecation banner to the top of each migrated map note (do not delete the file):
+
+```text
+> Deprecated: superseded by the DesignContext graph (.design/context-graph.json) as of Phase 52.
+> Read-only for one minor version; regenerate the graph with /gdd:migrate-context.
+```
+
+In `--dry-run`, describe this banner instead of writing it. Announce that the next minor version may remove
+the `.design/map/*.md` notes, and that the graph is now the source of truth.
+
+## Do Not
+
+- Do not trust a low-confidence transform silently. Every `could-not-fix:` line and every stub goes on the
+  Step 5 review list.
+- Do not delete `.design/map/*.md`. Add the deprecation banner and keep the notes for one minor version.
+- Do not hand-edit `.design/context-graph.json` to force validation green. Fix the fragment or the source,
+  then re-merge.
+- Do not edit the extractors, the merger, or the validator. This skill only calls them.
+
+## MIGRATE-CONTEXT COMPLETE

package/dist/claude-code/.claude/skills/progress/SKILL.md

@@ -86,6 +86,10 @@ After the pipeline state (and forensic audit if run), surface a one-line composi
 
 Run `scripts/validate-composition-graph.cjs` for the authoritative cycle and dangling-edge counts when that validator is present; until then report `0` and note the graph is not yet wired. This is a readiness hint, not a gate.
 
+## Step 3.6 - DesignContext graph coverage
+
+When `.design/context-graph.json` exists, surface one line for the typed DesignContext graph using the `coverage` helper in `scripts/lib/design-context-query.cjs` (`node scripts/lib/design-context-query.cjs coverage`), then point at the Atomic-Design map: `DesignContext graph: <pct>% node-type coverage | map: .design/INTEGRATION-MAP.md`. Skip this line entirely when the graph is absent (a pre-Phase-52 project); offer `/gdd:migrate-context` as the next step instead. Readiness hint, not a gate.
+
 ## Step 4 - Update notice (safe-window surface)
 
 After printing the pipeline state, emit the plugin-update banner if one is present. This file is written by `hooks/update-check.sh` subject to the state-machine guard (mid-pipeline stages suppress it) and per-version dismissal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.51.0",
+  "version": "1.53.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -59,7 +59,7 @@
     "test:behavior": "node scripts/run-behavior-tests.cjs",
     "typecheck": "tsc --noEmit",
     "codegen:schemas": "node --experimental-strip-types scripts/codegen-schema-types.ts",
-    "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#.planning\" \"#.claude\" \"#test/fixtures/baselines\"",
+    "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#**/node_modules\" \"#.planning\" \"#.claude\" \"#test/fixtures/baselines\"",
     "lint:links": "npx --yes lychee --no-progress --accept 200,206,403,429 \"**/*.md\" || true",
     "lint:agentskills": "node scripts/lint-agentskills-spec.cjs",
     "lint:changelog": "node scripts/lint-changelog.cjs",
@@ -74,6 +74,7 @@
     "check:domain-links": "node scripts/check-domain-cross-links.cjs",
     "check:no-duplication": "node scripts/check-no-duplication.cjs",
     "validate:composition-graph": "node scripts/validate-composition-graph.cjs",
+    "validate:design-context": "node scripts/validate-design-context.cjs",
     "validate:skill-frontmatter": "node scripts/validate-skill-frontmatter.cjs",
     "build:skill-graph": "node scripts/generate-skill-graph.cjs",
     "build:skill-graph:check": "node scripts/generate-skill-graph.cjs --check",

package/reference/design-context-schema.md

@@ -0,0 +1,159 @@
+---
+name: design-context-schema
+type: reference
+version: 1.0.0
+phase: 52
+tags: [design-context, knowledge-graph, schema, nodes, edges, mapper, two-phase]
+last_updated: 2026-06-03
+---
+
+# DesignContext Graph Schema
+
+The DesignContext graph is the typed knowledge graph of a design system. It records design
+entities as `nodes` and the relationships between them as `edges`, so an agent can reason about
+a system the way an engineer reads a dependency graph: which token a component consumes, which
+screen a flow transitions to, which pattern an anti-pattern conflicts with. The canonical graph
+lives at `.design/context-graph.json`. It is validated by `scripts/validate-design-context.cjs`
+and queried by `scripts/lib/design-context-query.cjs`.
+
+This file documents the four shapes (Node, Edge, Fragment, Graph), the ten node types, the twelve
+edge types, and the two-phase mapper pattern that builds the graph. The controlled `tags[]`
+vocabulary lives in `./design-context-tag-vocab.md`; the JSON Schema lives at
+`./schemas/design-context.schema.json`.
+
+## Shapes
+
+Four shapes make up the contract. A Graph is the assembled whole; a Fragment is one mapper's
+contribution before merge; Nodes and Edges are the parts.
+
+### Node
+
+```
+{ id, type, name, summary, tags[], complexity }
+```
+
+- `id`: stable unique string; edges reference it. A duplicate id is a hard error.
+- `type`: one of the ten node types below.
+- `name`: human-readable name of the entity.
+- `summary`: a one-line description of what the entity is and does. The deterministic pass may
+  leave this empty; the summary pass fills it. An empty summary, or one identical to `name`, is a
+  soft warning (a stub).
+- `tags[]`: strings from the controlled vocabulary. An unknown tag is a soft warning.
+- `complexity`: one of `simple`, `moderate`, `complex`.
+- `subtype` *(optional)*: a finer class. For a `token` node one of
+  `color / spacing / typography / radius / shadow`; for a `layer` node one of
+  `Atomic / Molecular / Organism / Template`.
+
+### Edge
+
+```
+{ source, target, type, direction, weight }
+```
+
+- `source`, `target`: node ids. Both must resolve to an existing node; a dangling endpoint is a
+  hard error.
+- `type`: one of the twelve edge types below.
+- `direction`: one of `forward`, `backward`, `bidirectional`. A forward edge reads
+  source-to-target; a backward edge reads target-to-source; a bidirectional edge reads both ways.
+  Traversal in the query library honors direction.
+- `weight`: a number in the inclusive range 0 to 1. It expresses relationship strength, not
+  distance, so a stronger tie has a higher weight.
+
+### Fragment
+
+```
+{ schema_version, mapper, generated_at, nodes[], edges[] }
+```
+
+A Fragment is the output of a single mapper (the Figma mapper, the codebase mapper, the docs
+mapper). It carries a `mapper` field naming its origin and is merged into the Graph by union on
+node `id`. Fragments let mappers run independently and write narrow outputs that later combine.
+
+### Graph
+
+```
+{ schema_version, generated_at, nodes[], edges[] }
+```
+
+The Graph is the merged, canonical document at `.design/context-graph.json`. `schema_version` is
+required; `generated_at` is an optional ISO-8601 timestamp recording when the graph was assembled.
+
+## Node types
+
+Ten node types cover the entities a design system holds. Each entry states what the type is and
+when a mapper emits it.
+
+- **token**: a design-token leaf such as a color, a spacing step, or a type ramp value. Emitted
+  for every resolvable token; carries a `subtype` naming the token family.
+- **component**: a reusable UI unit (a button, a card, an input). Emitted once per component
+  regardless of how many variants it has.
+- **variant**: a named configuration of a component (a button's `primary` or `ghost`). Emitted
+  when a component exposes distinct variants worth addressing on their own.
+- **state**: an interaction or lifecycle state of a component (`hover`, `disabled`, `loading`).
+  Emitted when state changes carry their own styling or behavior.
+- **motion-fragment**: a reusable motion unit (an enter transition, an easing curve, a loop).
+  Emitted when motion is named and reused rather than ad hoc.
+- **a11y-pattern**: an accessibility pattern (a focus-trap, a skip-link, an aria-live region).
+  Emitted when a component participates in a named accessibility contract.
+- **screen**: a full page or view in a product flow. Emitted once per distinct screen.
+- **layer**: a composition layer in the atomic taxonomy. Carries a `subtype` of `Atomic`,
+  `Molecular`, `Organism`, or `Template`. Emitted to record where an entity sits in the hierarchy.
+- **pattern**: a recurring solution that spans components (a master-detail layout, a wizard).
+  Emitted when a shape repeats across the system and earns a name.
+- **anti-pattern**: a recurring shape the system wants to retire (a one-off color, a duplicated
+  control). Emitted so the graph can point at debt and the edges can mark conflicts.
+
+## Edge types
+
+Twelve edge types cover how entities relate. Each entry states the relationship and when it
+applies.
+
+- **uses-token**: a component or variant consumes a token. Source is the consumer, target is the
+  token.
+- **composes**: a larger entity is built from a smaller one (a card composes a button). Source is
+  the whole, target is the part.
+- **extends**: a variant or component specializes another (a `primary` button extends the base
+  button). Source is the specialization.
+- **transitions-to**: a screen or state moves to another in a flow. Used for navigation graphs
+  and state machines.
+- **depends-on**: a generic dependency where the more specific edge types do not fit. Source
+  needs target to function.
+- **mirrors**: two entities are intentional reflections of each other (a light-mode and dark-mode
+  pair). Usually bidirectional.
+- **conflicts-with**: two entities collide or duplicate intent (an anti-pattern conflicts with a
+  sanctioned pattern). Used to surface debt.
+- **referenced-by**: an inbound citation: the target points at the source from outside the graph
+  core (a doc or a ticket references this entity). Often backward.
+- **tested-by**: an entity is covered by a test. Source is the entity, target is the test node.
+- **documented-by**: an entity is described by a doc. Source is the entity, target is the doc.
+- **consumes-context**: an entity reads shared context provided elsewhere (a component reads a
+  theme provider). Source is the reader.
+- **provides-context**: an entity supplies shared context to others (a theme provider supplies a
+  palette). Source is the provider; the matching reader uses `consumes-context`.
+
+## The two-phase mapper pattern
+
+A mapper builds the graph in two passes so the cheap, deterministic work is separate from the
+costly, judgment-bearing work.
+
+1. **Deterministic extract.** A pure pass walks the source (a Figma file, a component tree, a docs
+   set) and emits node and edge skeletons: ids, types, names, tags, complexity, and every edge it
+   can prove. Summaries are left empty. This pass is reproducible and dependency-free, so a graph
+   can be rebuilt the same way every run.
+2. **LLM summary.** A second pass fills each node `summary` with a one-line description an agent
+   can read. Only the `summary` field changes; ids, types, and edges stay fixed from the extract
+   pass. This keeps the expensive pass narrow and lets the validator flag any node the summary
+   pass missed as a stub.
+
+Splitting the work this way means the structure of the graph is deterministic and auditable, while
+the prose layer can be regenerated on its own without disturbing the topology. A mapper writes a
+Fragment; the assembler merges fragments into the canonical Graph.
+
+## Cross-references
+
+- Controlled `tags[]` vocabulary the validator enforces: see `./design-context-tag-vocab.md`.
+- The JSON Schema (Draft-07) for the Graph: see `./schemas/design-context.schema.json`.
+- The validator (structural, referential, completeness, tag checks):
+  `scripts/validate-design-context.cjs`.
+- The query library (filters, BFS path, consumers, orphans, cycles, coverage):
+  `scripts/lib/design-context-query.cjs`.

package/reference/design-context-tag-vocab.md

@@ -0,0 +1,82 @@
+---
+name: design-context-tag-vocab
+type: reference
+version: 1.0.0
+phase: 52
+tags: [design-context, knowledge-graph, tags, vocabulary, controlled-vocab]
+last_updated: 2026-06-03
+---
+
+# DesignContext Tag Vocabulary
+
+This is the controlled vocabulary the DesignContext validator checks node `tags[]` against. A tag
+outside this list is a soft warning, not a hard error, so a mapper can ship a new tag and the
+graph still loads; the warning prompts a reviewer to either fix the tag or add it here.
+
+## Source of truth
+
+The canonical list lives in code, in the `TAG_VOCAB` set inside
+`scripts/validate-design-context.cjs`. That set is what the validator enforces. This document
+mirrors it for human readers and groups the tags by concern. When the set changes, update this
+file by hand to match. If the two ever disagree, the code wins.
+
+## Why a controlled vocabulary
+
+Free-form tags drift: one node says `darkmode`, another `dark-mode`, a third `dark`. A query for
+`dark-mode` then misses two of three. A controlled list keeps tags queryable and keeps the
+`nodes(graph, { tag })` filter reliable. The list is deliberately broad rather than minimal, so
+most real tags land inside it; the soft-warning behavior absorbs the rest without blocking a build.
+
+## Tags by concern
+
+The groupings below are for reading only. The validator treats the vocabulary as one flat set, so
+a tag is valid regardless of which group it sits in.
+
+- **Color**: `color`, `palette`, `theme`, `dark-mode`, `light-mode`, `contrast`, `gradient`,
+  `surface`, `brand`.
+- **Spacing and sizing**: `spacing`, `sizing`, `density`, `gap`, `inset`, `stack`.
+- **Typography**: `typography`, `font`, `type-scale`, `heading`, `body-text`, `label`, `numeric`.
+- **Radius, shape, elevation**: `radius`, `shape`, `border`, `shadow`, `elevation`, `depth`.
+- **Motion**: `motion`, `transition`, `animation`, `easing`, `duration`, `enter`, `exit`, `loop`,
+  `gesture`.
+- **Accessibility**: `a11y`, `aria`, `focus`, `keyboard`, `screen-reader`, `reduced-motion`,
+  `contrast-safe`, `touch-target`.
+- **Layout and structure**: `layout`, `grid`, `flex`, `responsive`, `breakpoint`, `container`,
+  `overflow`, `position`, `z-index`.
+- **Interaction state**: `state`, `hover`, `active`, `disabled`, `loading`, `error`, `success`,
+  `selected`, `pressed`, `dragging`.
+- **Component taxonomy**: `atom`, `molecule`, `organism`, `template`, `primitive`, `composite`,
+  `layout-primitive`.
+- **Forms and inputs**: `form`, `input`, `control`, `validation`, `field`.
+- **Navigation and structure**: `navigation`, `overlay`, `modal`, `menu`, `tabs`, `data-display`,
+  `feedback`, `media`.
+- **Semantic role**: `interactive`, `static`, `decorative`, `destructive`, `utility`.
+- **Quality flags**: `deprecated`, `experimental`, `stable`, `anti-pattern`, `review-needed`.
+
+## Machine-readable list
+
+The fenced block below is the same vocabulary as a flat list for any tool that wants to read the
+doc instead of the code. Tokens are separated by commas or newlines (split on `/[\s,]+/`), so the
+grouping into lines is cosmetic. It must stay equal to the `TAG_VOCAB` set in
+`scripts/validate-design-context.cjs`.
+
+```text
+color, palette, theme, dark-mode, light-mode, contrast, gradient, surface, brand,
+spacing, sizing, density, gap, inset, stack,
+typography, font, type-scale, heading, body-text, label, numeric,
+radius, shape, border, shadow, elevation, depth,
+motion, transition, animation, easing, duration, enter, exit, loop, gesture,
+a11y, aria, focus, keyboard, screen-reader, reduced-motion, contrast-safe, touch-target,
+layout, grid, flex, responsive, breakpoint, container, overflow, position, z-index,
+state, hover, active, disabled, loading, error, success, selected, pressed, dragging,
+atom, molecule, organism, template, primitive, composite, layout-primitive,
+form, input, control, validation, field,
+navigation, overlay, modal, menu, tabs, data-display, feedback, media,
+interactive, static, decorative, destructive, utility,
+deprecated, experimental, stable, anti-pattern, review-needed
+```
+
+## Cross-references
+
+- The node and edge type catalogue and the four shapes: see `./design-context-schema.md`.
+- The validator that enforces this vocabulary: `scripts/validate-design-context.cjs`.

package/reference/registry.json

@@ -1156,6 +1156,20 @@
       "type": "meta-rules",
       "phase": 51,
       "description": "Phase 51 instinct unit format: YAML frontmatter (id, trigger, confidence 0.3-0.9, domain, scope, project_id, source, cycles_seen, first/last_seen) + body; promotion gate K=2/M=2; Beta(2,8) prior; TTL decay. Stored via scripts/lib/instinct-store.cjs."
+    },
+    {
+      "name": "design-context-schema",
+      "path": "reference/design-context-schema.md",
+      "type": "schema",
+      "phase": 52,
+      "description": "Phase 52 (KEYSTONE) typed DesignContext graph: 10 node types + 12 edge types, Node/Edge/Fragment/Graph shapes, two-phase mapper pattern. Schema at reference/schemas/design-context.schema.json."
+    },
+    {
+      "name": "design-context-tag-vocab",
+      "path": "reference/design-context-tag-vocab.md",
+      "type": "meta-rules",
+      "phase": 52,
+      "description": "Phase 52 controlled tag vocabulary for DesignContext nodes; validate-design-context.cjs soft-warns on unknown tags."
     }
   ]
 }

package/reference/schemas/design-context.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/hegemonart/get-design-done/reference/schemas/design-context.schema.json",
+  "title": "Design Context Graph",
+  "description": "The canonical typed knowledge graph of a design system, persisted at .design/context-graph.json. Nodes are design entities (tokens, components, screens, patterns); edges are typed relationships between them (uses-token, composes, transitions-to). Built by a two-phase mapper: a deterministic extract pass emits node/edge skeletons, then an LLM summary pass fills each node summary. Validated structurally by scripts/validate-design-context.cjs and queried by scripts/lib/design-context-query.cjs.",
+  "type": "object",
+  "required": ["schema_version", "nodes", "edges"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Schema version of this graph document (e.g. \"52.0\")."
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp the graph was last assembled (optional)."
+    },
+    "nodes": {
+      "type": "array",
+      "description": "All design entities in the graph. Node ids must be unique.",
+      "items": { "$ref": "#/definitions/node" }
+    },
+    "edges": {
+      "type": "array",
+      "description": "All typed relationships. Every source/target must resolve to a node id.",
+      "items": { "$ref": "#/definitions/edge" }
+    }
+  },
+  "additionalProperties": true,
+  "definitions": {
+    "node": {
+      "type": "object",
+      "required": ["id", "type", "name", "summary", "complexity"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable unique identifier for the node (referenced by edge source/target)."
+        },
+        "type": {
+          "type": "string",
+          "description": "The kind of design entity this node represents.",
+          "enum": [
+            "token",
+            "component",
+            "variant",
+            "state",
+            "motion-fragment",
+            "a11y-pattern",
+            "screen",
+            "layer",
+            "pattern",
+            "anti-pattern"
+          ]
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable name of the entity."
+        },
+        "summary": {
+          "type": "string",
+          "description": "One-line LLM-authored description of what the entity is and does. A stub summary (empty or identical to name) is flagged by the validator as a soft warning."
+        },
+        "tags": {
+          "type": "array",
+          "description": "Controlled-vocabulary tags grouping the node by concern (see reference/design-context-tag-vocab.md). Unknown tags are a soft warning, not a hard error.",
+          "items": { "type": "string" }
+        },
+        "complexity": {
+          "type": "string",
+          "description": "Coarse complexity bucket for the entity.",
+          "enum": ["simple", "moderate", "complex"]
+        },
+        "subtype": {
+          "type": "string",
+          "description": "Optional finer classification. For token nodes one of color/spacing/typography/radius/shadow; for layer nodes one of Atomic/Molecular/Organism/Template. Free-form for other node types."
+        }
+      },
+      "additionalProperties": true
+    },
+    "edge": {
+      "type": "object",
+      "required": ["source", "target", "type", "direction", "weight"],
+      "properties": {
+        "source": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Node id the edge originates from."
+        },
+        "target": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Node id the edge points to."
+        },
+        "type": {
+          "type": "string",
+          "description": "The kind of relationship between source and target.",
+          "enum": [
+            "uses-token",
+            "composes",
+            "extends",
+            "transitions-to",
+            "depends-on",
+            "mirrors",
+            "conflicts-with",
+            "referenced-by",
+            "tested-by",
+            "documented-by",
+            "consumes-context",
+            "provides-context"
+          ]
+        },
+        "direction": {
+          "type": "string",
+          "description": "Whether the relationship reads source-to-target (forward), target-to-source (backward), or both ways (bidirectional).",
+          "enum": ["forward", "backward", "bidirectional"]
+        },
+        "weight": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Relationship strength in the inclusive range 0..1."
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/reference/schemas/mcp-gdd-tools.schema.json

@@ -7,7 +7,7 @@
   "properties": {
     "tools": {
       "type": "object",
-      "description": "Per-tool input/output schemas keyed by tool name. Exactly 12 entries (D-03 hard cap).",
+      "description": "Per-tool input/output schemas keyed by tool name. Exactly 13 entries (D-03 cap, raised 12 -> 13 in Phase 52 for gdd_context_query).",
       "additionalProperties": false,
       "properties": {
         "gdd_status": {
@@ -33,6 +33,39 @@
             }
           }
         },
+        "gdd_context_query": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "properties": {
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["op"],
+              "properties": {
+                "op": {
+                  "type": "string",
+                  "enum": ["nodes", "edges", "path", "consumers-of", "unreachable", "cycles", "coverage"]
+                },
+                "type": { "type": "string" },
+                "tag": { "type": "string" },
+                "from": { "type": "string" },
+                "to": { "type": "string" },
+                "id": { "type": "string" }
+              }
+            },
+            "output": {
+              "type": "object",
+              "required": ["op", "graph_present", "result"],
+              "properties": {
+                "op": { "type": "string" },
+                "graph_present": { "type": "boolean" },
+                "path": { "type": "string" },
+                "result": { "type": ["array", "object", "null"] }
+              }
+            }
+          }
+        },
         "gdd_phase_current": {
           "type": "object",
           "additionalProperties": false,

package/reference/skill-graph.md

@@ -9,7 +9,7 @@ is a `composes_with` edge (the source calls the target as sub-orchestration); a
 a `next_skills` edge (a pipeline hint for what runs next). Stage grouping is best-effort and
 inferred from the skill name; skills with no stage keyword fall under Utility.
 
-Skills: 89. Composition edges: 0 composes_with, 6 next_skills.
+Skills: 91. Composition edges: 0 composes_with, 6 next_skills.
 
 ```mermaid
 flowchart TD
@@ -72,6 +72,7 @@ flowchart TD
     n_cache_manager["cache-manager"]
     n_check_update["check-update"]
     n_connections["connections"]
+    n_context["context"]
     n_continue["continue"]
     n_debug["debug"]
     n_extract_learnings["extract-learnings"]
@@ -83,6 +84,7 @@ flowchart TD
     n_instinct["instinct"]
     n_list_pins["list-pins"]
     n_locale["locale"]
+    n_migrate_context["migrate-context"]
     n_new_skill["new-skill"]
     n_next["next"]
     n_note["note"]