@hegemonart/get-design-done 1.50.1 → 1.52.0

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
 

package/agents/visual-hierarchy-mapper.md

@@ -11,6 +11,7 @@ typical-duration-seconds: 45
 reads-only: false
 writes:
   - ".design/map/visual-hierarchy.md"
+  - ".design/fragments/visual-hierarchy-mapper.json"
 ---
 
 @reference/shared-preamble.md
@@ -117,9 +118,37 @@ Total: N findings.
 ```
 ```
 
+## Graph fragment emission
+
+Dual-emit: keep writing `.design/map/visual-hierarchy.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-visual-hierarchy.mjs <source_root> [<source_root>...] > .design/fragments/visual-hierarchy-mapper.json
+```
+
+`extract-visual-hierarchy.mjs` walks the source roots with regex (zero-dep) and returns a Fragment whose `nodes[]` have `id`, `type` (`screen` for pages or routes, `pattern` for layout patterns, `anti-pattern` for hierarchy violations you flagged), and `name` filled, with stub `summary` you must replace.
+
+### 2. LLM phase (fill summary, tags, complexity)
+
+For every node the extractor produced, set:
+
+- `summary`: one sentence describing the screen or pattern and its hierarchy signal, distinct from `name`. Example for an F-pattern node: "Left-aligned scan path with stacked content blocks".
+- `tags[]`: pick from `reference/design-context-tag-vocab.md` only (hierarchy terms such as `f-pattern`, `z-pattern`, `centered`, `type-scale`, `focal-weight`). Drop any tag not in the vocab.
+- `complexity`: `simple` for a single layout pattern, `moderate` for a screen combining two patterns, `complex` for a screen with nested or competing focal regions.
+
+Add edges the extractor cannot infer: two screens sharing a layout pattern are `mirrors`; a flagged anti-pattern that contradicts a sibling screen's pattern is `conflicts-with`. Set `direction` and `weight` per the schema.
+
+### 3. Write the fragment
+
+Write the completed Fragment to `.design/fragments/visual-hierarchy-mapper.json` with `schema_version`, `mapper: "visual-hierarchy-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 git. No agent spawning.
+No modifications outside `.design/map/` and `.design/fragments/`. No git. No agent spawning.
 
 ## Record
 

package/dist/claude-code/.claude/skills/apply-reflections/SKILL.md

@@ -84,6 +84,23 @@ Incubator drafts authored by `scripts/lib/incubator-author.cjs` (Phase 29-04) ap
 
 KFM-catalogue proposals authored by `scripts/lib/reflector-kfm-proposer.cjs` (Phase 30.5-03 D-05) appear as a 6th proposal class. Drafts at `.design/reflections/incubator/kfm-<slug>/CATALOGUE-ENTRY.md`; pre-filled 11-field schema with `TODO:` placeholders for `pattern` + `fix`. Two upstream signals share the surface (D-06): `capability_gap` clusters (≥3, no existing match) + `kfm-candidate` events (whitelist-matched articles, 1-shot). User chooses **accept** | **reject** | **defer** | **edit**. `applyAccept` appends to `reference/known-failure-modes.md` + `reference/registry.json` (`origin: incubator-kfm`); `applyReject` removes the incubator subdir; `applyDefer` stamps `deferred_until`; `applyEdit` returns the draft path for `$EDITOR`. Full procedure: `./apply-reflections-procedure.md` §[KFM-CANDIDATE].
 
+## [INSTINCT]
+
+Atomic instinct units emitted by `design-reflector` (and surfaced from `/gdd:extract-learnings`) appear as a distinct proposal class, alongside `[INCUBATOR]` and `[KFM-CANDIDATE]`. Each unit is a fenced `yaml` block under the reflector's `## Atomic instincts` section, shaped per `reference/instinct-format.md` (`id`, `trigger`, `confidence`, `domain`, `scope`, `project_id`, `source`, `cycles_seen`, `first_seen`, `last_seen`, plus a short body). A unit is a proposal, never a stored fact - nothing lands until the user accepts it.
+
+Mirror the `[INCUBATOR]` flow:
+
+1. Discover the units: parse every `yaml` block under `## Atomic instincts` in the reflections file. Skip malformed blocks (warn on stderr, keep going).
+2. For each unit: show the parsed `trigger`, `domain`, `confidence`, and body so the user sees what would be stored.
+3. Prompt: `(a) accept   (r) reject   (d) defer   (e) edit   (q) quit`.
+
+**Per-action behavior:**
+
+1. **accept** - call `scripts/lib/instinct-store.cjs` `add(unit, { scope, baseDir })` with the unit at its emitted `confidence`. The store owns de-duplication and `cycles_seen` bookkeeping. On success print `Stored instinct <id> (<domain>, confidence <n>).` and append `**Applied**: <date>` to the proposal block.
+2. **reject** - do not store the unit. Append `**Reviewed: rejected**` to the reflections file.
+3. **defer** - no-op; the unit re-surfaces next run. Append `**Reviewed: deferred**`.
+4. **edit** - let the user adjust `trigger`, `confidence`, or `domain`, then accept the edited unit through the same `add(...)` call. Default `scope: 'project'` (write `global` only when the unit's frontmatter says so); never edit `.design/instincts/instincts.json` directly, and promote to global via the separate gated `/gdd:instinct promote`.
+
 ## Do Not
 
 - Do not apply any proposal without the user explicitly choosing `a` or `e`.

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

@@ -0,0 +1,137 @@
+---
+name: gdd-context
+description: "Queries the typed DesignContext graph at .design/context-graph.json - the design-semantic map of tokens, components, variants, states, motion, a11y patterns, screens, layers, and design patterns plus the edges between them. Lists and filters nodes and edges, traces a path between two nodes, finds the consumers of a node, and reports unreachable nodes, dependency cycles, and coverage. Use when the user wants to inspect the design graph, find what depends on a token or component, trace how one node reaches another, or check graph health. Activates for requests involving the design context graph, design dependencies, token consumers, component composition, unreachable design nodes, design cycles, or design coverage."
+argument-hint: "[nodes --type X | edges --type Z | path <a> <b> | consumers-of <id> | unreachable | cycles | coverage]"
+tools: Read, Bash
+user-invocable: true
+---
+
+# /gdd:context
+
+**Role:** Read-only front end for the typed DesignContext graph. The graph is a design-semantic map: nodes are tokens, components, variants, states, motion fragments, a11y patterns, screens, layers, and design patterns; edges connect them (uses-token, composes, extends, transitions-to, depends-on, mirrors, conflicts-with, referenced-by, tested-by, documented-by, consumes-context, provides-context). This skill queries that graph. It never writes to it. The graph is authored by the mapper agents plus the design-research-synthesizer; this skill only reads.
+
+The query engine ships at `scripts/lib/design-context-query.cjs` (authored elsewhere; this skill only calls it). It is pure and dep-free, exposing `load`, `nodes`, `edges`, `path`, `consumersOf`, `unreachable`, `cycles`, and `coverage`. The merged graph lives at `.design/context-graph.json` with the shape `{ schema_version, generated_at, nodes[], edges[] }`.
+
+If `.design/context-graph.json` is absent, print: `No DesignContext graph yet. Run the design research pipeline (mappers plus /gdd:synthesize) to generate .design/context-graph.json.` Then STOP. Do not invent a graph.
+
+The engine exposes a module API rather than a CLI, so drive it from a short `node -e` script, the same way other skills call a `scripts/lib` helper:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.nodes(g, { type: process.env.NODE_TYPE || undefined, tag: process.env.TAG || undefined })));"
+```
+
+## Invocation Modes
+
+| Command | Behavior |
+|---|---|
+| `/gdd:context nodes` | List graph nodes, optionally filtered by `--type` and `--tag` (default mode). |
+| `/gdd:context edges` | List graph edges, optionally filtered by `--type`. |
+| `/gdd:context path <a> <b>` | Trace a path from node `<a>` to node `<b>`. |
+| `/gdd:context consumers-of <id>` | List the nodes that consume node `<id>`. |
+| `/gdd:context unreachable` | List nodes no edge reaches. |
+| `/gdd:context cycles` | List dependency cycles in the graph. |
+| `/gdd:context coverage` | Report graph coverage (typed and tagged ratios). |
+
+Output discipline: emit JSON when a tool or another skill is the caller; render a compact table when a person is at the terminal.
+
+## nodes
+
+List nodes. `--type <t>` filters by node type (token, component, variant, state, motion-fragment, a11y-pattern, screen, layer, pattern, anti-pattern). `--tag <tag>` filters by a controlled tag. Call `nodes(graph, { type, tag })`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.nodes(g, { type: process.env.NODE_TYPE || undefined, tag: process.env.TAG || undefined })));"
+```
+
+Render one row per node. Keep it scannable:
+
+```
+ID                  TYPE        COMPLEXITY  NAME
+token:color/brand   token       simple      Brand primary
+component:Button    component   moderate    Button
+```
+
+If no nodes match, say so plainly and suggest a broader filter.
+
+## edges
+
+List edges. `--type <t>` filters by edge type (uses-token, composes, extends, transitions-to, depends-on, mirrors, conflicts-with, referenced-by, tested-by, documented-by, consumes-context, provides-context). Call `edges(graph, { type })`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.edges(g, { type: process.env.EDGE_TYPE || undefined })));"
+```
+
+Render `source -> target (type, weight)` per row. If none match, report it and suggest dropping the filter.
+
+## path
+
+Trace a path between two node ids. Call `path(graph, from, to)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.path(g, process.env.FROM, process.env.TO)));"
+```
+
+Print the ordered node ids joined by arrows. If no path exists, print `No path from <a> to <b>.` Do not fabricate intermediate nodes.
+
+## consumers-of
+
+List the nodes that consume a given node (the inbound side). Call `consumersOf(graph, id)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.consumersOf(g, process.env.ID)));"
+```
+
+Render the consumer ids one per row. If the id is unknown, print `No node <id> in the graph.` and suggest `/gdd:context nodes`.
+
+## unreachable
+
+List nodes that no edge reaches (orphans). Call `unreachable(graph)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.unreachable(g)));"
+```
+
+If the list is empty, print `Every node is reachable.`
+
+## cycles
+
+List dependency cycles. Call `cycles(graph)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.cycles(g)));"
+```
+
+Print each cycle as its ordered node ids. If there are none, print `No cycles detected.`
+
+## coverage
+
+Report graph coverage. Call `coverage(graph)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.coverage(g)));"
+```
+
+Surface the returned ratios (for example typed and tagged coverage and node and edge counts) as a short summary.
+
+## Do Not
+
+- Do not edit `.design/context-graph.json` or the fragments under `.design/fragments/`. All writes go through the mapper agents and the synthesizer.
+- Do not invent nodes, edges, or paths. If a query returns nothing, report it plainly.
+- Do not modify `scripts/lib/design-context-query.cjs` or the DesignContext schema.
+
+## CONTEXT COMPLETE

package/dist/claude-code/.claude/skills/extract-learnings/SKILL.md

@@ -53,6 +53,22 @@ Layout of `.design/learnings/LEARNINGS.md`:
 ---
 ```
 
+### Step 3b - Dual-emit atomic instinct units (Phase 51)
+
+Alongside the prose `LEARNINGS.md`, emit atomic instinct units for every learning the extractor tags as an `instinct-candidate`. A learning is an `instinct-candidate` when it states a single trigger plus a one-line response - the same shape the reflector emits. Broader narrative learnings stay prose-only.
+
+For each `instinct-candidate`, build a unit per `reference/instinct-format.md` (frontmatter: `id`, `trigger`, `confidence` from 0.3 to 0.9, `domain`, `scope`, `project_id`, `source`, `cycles_seen`, `first_seen`, `last_seen`, plus a short body). Set `source: extract-learnings`. Carry the learning's confidence (high / medium / low) into the numeric field (roughly 0.8 / 0.55 / 0.35), capped at 0.9.
+
+Write each unit through the store engine `scripts/lib/instinct-store.cjs` rather than by hand:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs" add --scope project
+```
+
+If the engine exposes a module API only, drive `add(unit, { scope: 'project', baseDir })` from a short `node -e` script. The engine owns de-duplication and `cycles_seen` bookkeeping; do not pre-merge.
+
+The prose `LEARNINGS.md` is **retained read-only for one minor version** so existing readers keep working while tooling migrates to the units. Keep writing it; do not drop the prose path in this version.
+
 ### Step 4 - Reference file proposal (optional)
 
 After writing LEARNINGS.md, check each learning entry with `Proposed reference update: yes`.

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

@@ -0,0 +1,111 @@
+---
+name: gdd-instinct
+description: "Inspects and manages atomic instinct learning units - small, scoped, confidence-weighted patterns the pipeline accumulates across cycles. Lists the project and global instinct stores, searches them by keyword, and promotes a vetted project instinct to the global store once it has cleared the cross-project gate. Use when the user wants to see what instincts exist, find an instinct by topic, or promote one to global scope. Activates for requests involving instincts, learned patterns, instinct promotion, instinct search, or the instinct store."
+argument-hint: "[list | query <keyword> | promote <id>] [--scope project|global] [--domain <d>]"
+tools: Read, Bash
+user-invocable: true
+---
+
+# /gdd:instinct
+
+**Role:** Front end for the atomic instinct store. An instinct is a single learned pattern with a trigger, a confidence between 0.3 and 0.9, a domain, and a scope. This skill lists, searches, and promotes instincts. It never edits stored units by hand and never invents new ones - the reflector and `/gdd:extract-learnings` author them.
+
+The store engine ships at `scripts/lib/instinct-store.cjs` (authored elsewhere - this skill only calls it). Unit shape (YAML frontmatter plus a short body) is specified in `reference/instinct-format.md`. The project store lives at `.design/instincts/instincts.json`; the global store at `~/.claude/gdd/global-instincts.json`.
+
+Invoke the engine with `node`, the same way other skills call a `scripts/lib` helper:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs" <subcommand> [args]
+```
+
+If the engine exposes only a module API rather than a CLI, drive it from a short `node -e` script:
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); console.log(JSON.stringify(s.list({scope:process.env.SCOPE})))"
+```
+
+## Invocation Modes
+
+| Command | Behavior |
+|---|---|
+| `/gdd:instinct list` | Compact table of stored instincts (default mode). |
+| `/gdd:instinct query "<keyword>"` | Search instincts by keyword; show the top matches. |
+| `/gdd:instinct promote <id>` | Promote one project instinct to the global store (gated). |
+
+Flags apply across modes:
+
+- `--scope project|global` selects which store to read. Default is `project`.
+- `--domain <d>` filters to one domain (the domain enum is defined in `reference/instinct-format.md`).
+
+## list
+
+Read the requested store and print a compact table. Call `instinct-store.list({ scope, domain, baseDir })`:
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); \
+  const rows=s.list({ scope: process.env.SCOPE || 'project', domain: process.env.DOMAIN || undefined }); \
+  console.log(JSON.stringify(rows));"
+```
+
+Render one row per instinct. Keep it scannable:
+
+```
+ID        DOMAIN     CONF   CYCLES  TRIGGER
+in-7f3a   tokens     0.72   3       palette has no neutral ramp
+in-91bc   layout     0.55   2       cards overflow on the 320px breakpoint
+```
+
+- `CONF` is the stored confidence (0.3 to 0.9).
+- `CYCLES` is `cycles_seen`.
+- Truncate `TRIGGER` to keep each line on one row.
+
+If the store is empty, print: `No instincts in the <scope> store yet. Run /gdd:reflect or /gdd:extract-learnings to accumulate some.`
+
+## query
+
+Search by keyword and show the closest matches. Call `instinct-store.query(keyword, { scope, baseDir, limit })`. The engine uses an FTS5 index when one is present and falls back to a plain scan otherwise; either path returns the same row shape.
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); \
+  const hits=s.query(process.env.KW, { scope: process.env.SCOPE || 'project', limit: 10 }); \
+  console.log(JSON.stringify(hits));"
+```
+
+Print the top matches in the same table shape as `list`, ordered by the engine's relevance ranking. If there are no matches, say so plainly and suggest a broader keyword. Quote multi-word keywords so the shell passes one argument.
+
+## promote
+
+Promote a single project instinct into the global store so it applies across every project. Promotion is **gated**: `instinct-store.promote(id, { baseDir })` only succeeds when the instinct has been seen across at least K cycles (K=2) spanning at least M distinct project ids (M=2). The engine enforces the gate; this skill surfaces the outcome and asks the user to confirm before the write.
+
+Confirm first. Prefer `@clack/prompts`, and fall back to `AskUserQuestion` when it is absent (mirror the probe in `/gdd:new-skill`):
+
+```bash
+node -e "try { require.resolve('@clack/prompts'); console.log('clack'); } catch { console.log('fallback'); }"
+```
+
+- `clack`: drive `clack.confirm({ message: 'Promote <id> to the global store?' })` from a short Node script.
+- `fallback`: ask the same yes or no question with `AskUserQuestion`.
+
+On a confirmed yes, run the promotion:
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); \
+  console.log(JSON.stringify(s.promote(process.env.ID, {})));"
+```
+
+Branch on the engine result:
+
+- Promotion succeeded: print `Promoted <id> to the global store.` and show the new global row.
+- Gate not met: the engine reports how far the instinct is from the K=2 / M=2 bar. Print that plainly, for example `<id> needs 2 cycles across 2 projects; seen 1 cycle in 1 project so far. Not promoted.` Do not retry and do not force the write.
+- Unknown id: print `No instinct <id> in the project store.` and suggest `/gdd:instinct list`.
+
+If the user answers no at the confirm step, print `Promotion cancelled.` and exit without writing.
+
+## Do Not
+
+- Do not edit `.design/instincts/instincts.json` or the global store by hand. All writes go through `scripts/lib/instinct-store.cjs`.
+- Do not author new instincts here. The reflector and `/gdd:extract-learnings` emit units; this skill reads and promotes them.
+- Do not bypass the promotion gate. If the K=2 / M=2 bar is not met, report it and stop.
+- Do not modify `reference/instinct-format.md` or the store engine.
+
+## INSTINCT COMPLETE

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.