@hegemonart/get-design-done 1.50.1 → 1.52.0

package/sdk/mcp/gdd-mcp/server.ts

@@ -14,7 +14,8 @@
 //      Zod shapes, and our per-tool schemas are Draft-07 JSON.)
 //   2. Register `tools/list` — returns the registered tools with their
 //      input JSON Schemas loaded from disk. Scaffold ships with 0
-//      tools; Plan 27.7-02 populates `TOOL_MODULES` with 12 entries.
+//      tools; Plan 27.7-02 populated `TOOL_MODULES` with 12 entries;
+//      Phase 52 raised it to 13 (gdd_context_query, D5).
 //   3. Register `tools/call` — dispatches by name to the matching
 //      handler. Each handler returns a typed ToolResponse; the server
 //      wraps it into the MCP CallToolResult shape. Unknown tool names
@@ -89,8 +90,8 @@ function here(): string {
  *  restart, which matches every other part of the pipeline.
  *
  *  Scaffold ships with 0 tools — loadTools() returns []. Plan 27.7-02
- *  adds 12 tool modules, each with its own `schemaPath` pointing into
- *  `sdk/mcp/gdd-mcp/schemas/`. */
+ *  added 12 tool modules; Phase 52 raised it to 13. Each has its own
+ *  `schemaPath` pointing into `sdk/mcp/gdd-mcp/schemas/`. */
 interface LoadedTool extends ToolModule {
   inputSchema: Record<string, unknown>;
 }
@@ -124,12 +125,14 @@ function loadTools(): LoadedTool[] {
  * Tool descriptions — short, scannable, lifted from the plan. Skill
  * prose uses these verbatim when suggesting a tool to the model.
  *
- * Plan 27.7-02 populates 12 entries — one per tool name in the canonical
- * 12-tool list.
+ * Plan 27.7-02 populated 12 entries; Phase 52 added a 13th
+ * (gdd_context_query) — one per tool name in the canonical 13-tool list.
  */
 export const TOOL_DESCRIPTIONS: Record<string, string> = {
   gdd_status:
     'gdd_status: current cycle phase, branch, last-3 decisions, last-3 completed plans, blocker count.',
+  gdd_context_query:
+    'gdd_context_query: read-only query over the DesignContext graph (.design/context-graph.json) — op one of nodes/edges/path/consumers-of/unreachable/cycles/coverage; structured no-graph result when absent.',
   gdd_phase_current:
     'gdd_phase_current: STATE.md <position> block (phase, stage, task_progress, status).',
   gdd_phases_list:
@@ -159,6 +162,7 @@ export const TOOL_DESCRIPTIONS: Record<string, string> = {
  *  modify disk. v1 is read-only (D-04) so every entry is `true`. */
 export const TOOL_READONLY: Record<string, boolean> = {
   gdd_status: true,
+  gdd_context_query: true,
   gdd_phase_current: true,
   gdd_phases_list: true,
   gdd_plans_list: true,

package/sdk/mcp/gdd-mcp/tools/gdd_context_query.ts

@@ -0,0 +1,35 @@
+// sdk/mcp/gdd-mcp/tools/gdd_context_query.ts
+//
+// Phase 52 (DesignContext graph keystone). Read-only query surface over the
+// typed DesignContext graph at `.design/context-graph.json`. Thin tool: the
+// fs read + every query lives in scripts/lib/design-context-query.cjs (sibling
+// A); this file only dispatches `op`. Graceful: a missing/unreadable graph
+// returns a structured `{ graph_present: false }` result rather than throwing
+// (the same missing-data discipline the other read tools follow).
+
+import {
+  load, nodes, edges, path as findPath, consumersOf, unreachable, cycles, coverage,
+} from '../../../../scripts/lib/design-context-query.cjs';
+import { errorResponse, okResponse, resolveProjectRoot, type ToolResponse } from './shared.ts';
+
+export const name = 'gdd_context_query';
+export const schemaPath = '../schemas/gdd_context_query.schema.json';
+
+interface CtxInput { op?: string; type?: string; tag?: string; from?: string; to?: string; id?: string; }
+
+export async function handle(input: unknown): Promise<ToolResponse> {
+  try {
+    const t = (input ?? {}) as CtxInput;
+    let graph: unknown = null;
+    const ops: Record<string, () => unknown> = {
+      nodes: () => nodes(graph, { type: t.type, tag: t.tag }), edges: () => edges(graph, { type: t.type }),
+      path: () => findPath(graph, t.from, t.to), 'consumers-of': () => consumersOf(graph, t.id),
+      unreachable: () => unreachable(graph), cycles: () => cycles(graph), coverage: () => coverage(graph),
+    };
+    const fn = t.op ? ops[t.op] : undefined;
+    if (!fn) return errorResponse(new Error('op is required — one of: ' + Object.keys(ops).join(', ')));
+    try { graph = load(resolveProjectRoot() + '/.design/context-graph.json'); } catch { graph = null; }
+    if (!graph) return okResponse({ op: t.op, graph_present: false, result: null });
+    return okResponse({ op: t.op, graph_present: true, result: fn() });
+  } catch (err) { return errorResponse(err); }
+}

package/sdk/mcp/gdd-mcp/tools/index.ts

@@ -1,8 +1,9 @@
 // sdk/mcp/gdd-mcp/tools/index.ts
 //
-// Tool registry for `gdd-mcp`. Plan 27.7-02 populates with 12 read-only
-// tools. The 12-tool cap is D-03 (hard); enforced at module load by a
-// runtime check + by tests in Plan 27.7-03.
+// Tool registry for `gdd-mcp`. Plan 27.7-02 populated this with 12 read-only
+// tools. Phase 52 (DesignContext keystone, D5) adds a 13th read-only tool
+// (`gdd_context_query`) and bumps the cap 12 -> 13. The cap is D-03 (hard);
+// enforced at module load by a runtime check + by tests in Plan 27.7-03.
 //
 // Convention (mirrors Phase 20 `gdd-state`):
 //   - Each tool exports `name`, `schemaPath`, and `handle` from its own
@@ -15,6 +16,7 @@
 
 import type { ToolResponse } from './shared.ts';
 
+import * as gdd_context_query from './gdd_context_query.ts';
 import * as gdd_cycle_recap from './gdd_cycle_recap.ts';
 import * as gdd_decisions_list from './gdd_decisions_list.ts';
 import * as gdd_events_tail from './gdd_events_tail.ts';
@@ -39,12 +41,14 @@ export interface ToolModule {
 }
 
 /**
- * Canonical tool registry. 12 tools (D-03 hard cap). Order is
+ * Canonical tool registry. 13 tools (D-03 cap, raised 12 -> 13 in Phase 52
+ * for the read-only `gdd_context_query` DesignContext surface, D5). Order is
  * alphabetical (after `gdd_status` which leads as the canonical entry).
  * All tools are advertised equivalently in `tools/list`.
  */
 export const TOOL_MODULES: readonly ToolModule[] = [
   gdd_status,
+  gdd_context_query,
   gdd_cycle_recap,
   gdd_decisions_list,
   gdd_events_tail,
@@ -58,18 +62,19 @@ export const TOOL_MODULES: readonly ToolModule[] = [
   gdd_telemetry_query,
 ] as const;
 
-/** Canonical count. The plan caps this at 12 — if you add a tool past
- *  that bound, update the plan, the combined schema, and the lint
+/** Canonical count. The cap is 13 (raised from 12 in Phase 52) — if you add a
+ *  tool past that bound, update the plan, the combined schema, and the lint
  *  test (Plan 27.7-03). */
 export const TOOL_COUNT: number = TOOL_MODULES.length;
 
-// Module-load runtime assertion of the 12-tool cap (D-03). A compile-time
-// type guard is fragile against `readonly ToolModule[]` (the length type
-// widens to `number`); the runtime check is cheap, deterministic, and
-// fails fast on server boot if the registry ever drifts past the cap.
-if (TOOL_COUNT > 12) {
+// Module-load runtime assertion of the 13-tool cap (D-03, raised from 12 in
+// Phase 52). A compile-time type guard is fragile against `readonly
+// ToolModule[]` (the length type widens to `number`); the runtime check is
+// cheap, deterministic, and fails fast on server boot if the registry ever
+// drifts past the cap.
+if (TOOL_COUNT > 13) {
   throw new Error(
-    `gdd-mcp: TOOL_COUNT=${TOOL_COUNT} exceeds the 12-tool cap (D-03). ` +
-      'Add tool past 12 requires re-scoping in a new plan.',
+    `gdd-mcp: TOOL_COUNT=${TOOL_COUNT} exceeds the 13-tool cap (D-03, raised ` +
+      'from 12 in Phase 52). Adding a tool past 13 requires re-scoping in a new plan.',
   );
 }

package/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/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/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/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/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/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.