@hegemonart/get-design-done 1.51.0 → 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/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/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.