@hegemonart/get-design-done 1.50.1 → 1.52.0

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

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

package/reference/schemas/events.schema.json

@@ -10,7 +10,7 @@
     "type": {
       "type": "string",
       "minLength": 1,
-      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick, verify_outcome, rollout_started, rollout_advanced, rollout_stuck, budget_forecast, project_cap_warning, project_cap_halt, live_session_start, live_pick, live_generate, live_accept, live_discard, live_session_end."
+      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick, verify_outcome, rollout_started, rollout_advanced, rollout_stuck, budget_forecast, project_cap_warning, project_cap_halt, live_session_start, live_pick, live_generate, live_accept, live_discard, live_session_end, instinct_emitted, instinct_promoted, instinct_decayed."
     },
     "timestamp": {
       "type": "string",

package/reference/schemas/instinct.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/hegemonart/get-design-done/reference/schemas/instinct.schema.json",
+  "title": "Instinct Unit",
+  "description": "An atomic, confidence-weighted design instinct learned across cycles. Validates the YAML frontmatter object of an instinct unit (see reference/instinct-format.md). Project-scoped units live at <root>/instincts/instincts.json; promoted global units live at ~/.claude/gdd/global-instincts.json. Persisted + queried by scripts/lib/instinct-store.cjs.",
+  "type": "object",
+  "required": ["id", "trigger", "confidence", "domain", "scope", "source"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "minLength": 3,
+      "maxLength": 80,
+      "description": "Kebab-case stable identifier, e.g. \"prefer-token-over-hex\". Lowercase letters, digits, single hyphens."
+    },
+    "trigger": {
+      "type": "string",
+      "minLength": 8,
+      "maxLength": 280,
+      "description": "One sentence naming the situation that fires the instinct, e.g. \"When a color literal appears in a component, reach for a design token first.\""
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0.3,
+      "maximum": 0.9,
+      "description": "Posterior trust in the instinct. Floor 0.3 (a fresh instinct is advisory, never directive); ceiling 0.9 (no instinct is ever certain). TTL decay multiplies this by 0.9 when the instinct goes unsurfaced."
+    },
+    "domain": {
+      "type": "string",
+      "enum": ["intake", "explore", "decide", "build", "verify", "operate", "utility"],
+      "description": "Lifecycle stage the instinct applies to, aligned to the Phase 50 lifecycle stages."
+    },
+    "scope": {
+      "type": "string",
+      "enum": ["project", "global"],
+      "description": "project = learned from one repository; global = promoted after the K/M gate across distinct projects."
+    },
+    "project_id": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}$",
+      "description": "8-char hex sha of the normalized git origin the instinct was first learned from. Required for project scope; optional for global (a promoted instinct is no longer tied to one origin)."
+    },
+    "source": {
+      "type": "string",
+      "enum": ["reflection", "extract-learnings", "user"],
+      "description": "Which producer minted the instinct: a reflection pass, the extract-learnings step, or a direct user assertion."
+    },
+    "cycles_seen": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "How many distinct design cycles have surfaced this instinct. Feeds the K=2 half of the promotion gate."
+    },
+    "project_ids": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[0-9a-f]{8}$" },
+      "uniqueItems": true,
+      "description": "Set of distinct project ids that have surfaced this instinct. Its length feeds the M=2 half of the promotion gate."
+    },
+    "first_seen": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO date (YYYY-MM-DD) the instinct was first recorded."
+    },
+    "last_seen": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO date (YYYY-MM-DD) the instinct was last surfaced. Resets the TTL decay window."
+    },
+    "alpha": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Beta posterior success weight. Seeded from the Beta(2,8) prior on promotion."
+    },
+    "beta": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Beta posterior failure weight. Seeded from the Beta(2,8) prior on promotion."
+    },
+    "prior_class": {
+      "type": "string",
+      "description": "Tag recording which prior class seeded the posterior, e.g. \"instinct\"."
+    }
+  },
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "if": { "properties": { "scope": { "const": "project" } } },
+      "then": { "required": ["project_id"] }
+    }
+  ]
+}

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

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

package/reference/skill-graph.md

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

package/scripts/lib/design-context/extract-a11y.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// scripts/lib/design-context/extract-a11y.mjs — Phase 52 (DesignContext graph), executor B.
+//
+// Deterministic, dependency-free accessibility extractor. Regex-scans source
+// for ARIA attributes, role=, keyboard handlers, focus states, semantic
+// landmarks, skip links, and image alt coverage, and emits a Fragment
+// (schema_version 52.0) of `a11y-pattern` nodes with `documented-by` /
+// `referenced-by` edges:
+//   - component file --referenced-by--> a11y-pattern  (the file exhibits the pattern)
+//   - a11y-pattern --documented-by--> wcag:<criterion> node  (when a known pattern
+//     maps to a WCAG criterion we recognize)
+//
+// Semantics mirror agents/a11y-mapper.md (ARIA / keyboard / focus / landmarks /
+// alt). Static-only — no live browser. Structural pass: summary='' and
+// complexity='moderate' are stubs the LLM/mapper phase fills later. No network,
+// no deps, no top-level Date.now() (stamped in main()).
+//
+// Public API:
+//   extract(roots, opts?) -> Fragment   (pure)
+//   main()                              -> prints Fragment JSON to stdout
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const MAPPER = 'a11y-mapper';
+const SCHEMA_VERSION = '52.0';
+
+const SCANNABLE_EXT = new Set([
+  '.tsx', '.jsx', '.ts', '.js',
+  '.vue', '.svelte', '.html', '.htm',
+  '.css', '.scss',
+]);
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', 'coverage',
+  '.design', '.planning', 'out', '.cache', '.turbo', '.svelte-kit',
+]);
+
+function walk(root) {
+  const out = [];
+  let st;
+  try { st = fs.statSync(root); } catch { return out; }
+  if (st.isFile()) {
+    if (SCANNABLE_EXT.has(path.extname(root).toLowerCase())) out.push(root);
+    return out;
+  }
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) stack.push(full); }
+      else if (e.isFile() && SCANNABLE_EXT.has(path.extname(e.name).toLowerCase())) out.push(full);
+    }
+  }
+  return out;
+}
+
+function slug(s) {
+  return String(s).trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'x';
+}
+function stubNode(id, type, name, extra) {
+  return { id, type, name, summary: '', tags: [], complexity: 'moderate', ...extra };
+}
+
+// ---------------------------------------------------------------------------
+// A11y matchers + WCAG mapping.
+// ---------------------------------------------------------------------------
+
+const ARIA_ATTR = /\baria-([a-z]+)\s*=/g;
+const ROLE_ATTR = /\brole\s*=\s*["']([a-z]+)["']/g;
+const KEYBOARD = /\b(?:tabIndex|tabindex|onKeyDown|onKeyPress|onKeyUp|on:keydown)\b/g;
+const FOCUS_STATE = /:focus(?:-visible)?|focus-visible:|focus:/g;
+const LANDMARK = /<(header|nav|main|section|article|aside|footer)\b/g;
+const SKIP_LINK = /(?:skip-nav|skip-to-content|skip-link|#main-content)/g;
+const IMG_TAG = /<img\b[^>]*>/gi;
+
+// pattern-id -> WCAG criterion it satisfies/relates to.
+const WCAG_FOR_PATTERN = {
+  'aria-attributes': '4.1.2',
+  'role-semantics': '4.1.2',
+  'keyboard-support': '2.1.1',
+  'focus-visible': '2.4.7',
+  'semantic-landmarks': '1.3.1',
+  'skip-link': '2.4.1',
+  'image-alt': '1.1.1',
+};
+
+function collect(re, content, mapFn) {
+  const out = [];
+  re.lastIndex = 0;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    const v = mapFn(m);
+    if (v != null) out.push(v);
+    if (m.index === re.lastIndex) re.lastIndex++;
+  }
+  return out;
+}
+
+/**
+ * Pure extractor.
+ * @param {string[]|string} roots
+ * @param {{generatedAt?: string}} [opts]
+ * @returns {object} Fragment
+ */
+export function extract(roots, opts = {}) {
+  const rootList = (Array.isArray(roots) ? roots : [roots]).filter(Boolean);
+  const nodeMap = new Map();
+  const edgeSet = new Map();
+
+  const addPattern = (patternId, name, extra) => {
+    const id = `a11y-pattern:${patternId}`;
+    if (!nodeMap.has(id)) nodeMap.set(id, stubNode(id, 'a11y-pattern', name, extra || {}));
+    return id;
+  };
+  const addEdge = (source, target, type, weight) => {
+    const key = `${source}--${type}-->${target}`;
+    if (!edgeSet.has(key)) edgeSet.set(key, { source, target, type, direction: 'forward', weight });
+  };
+  // a11y-pattern --documented-by--> wcag criterion node.
+  const linkWcag = (patternKey, patternNodeId) => {
+    const crit = WCAG_FOR_PATTERN[patternKey];
+    if (!crit) return;
+    const wid = `pattern:wcag-${slug(crit)}`;
+    if (!nodeMap.has(wid)) nodeMap.set(wid, stubNode(wid, 'pattern', `WCAG ${crit}`, { criterion: crit }));
+    addEdge(patternNodeId, wid, 'documented-by', 0.8);
+  };
+
+  for (const root of rootList) {
+    for (const abs of walk(root)) {
+      let content;
+      try { content = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+      const ext = path.extname(abs).toLowerCase();
+      const baseName = path.basename(abs, ext);
+      const compId = `component:${slug(baseName)}`;
+
+      // Detect each pattern family present in this file.
+      const aria = collect(ARIA_ATTR, content, (m) => m[1]);
+      const roles = collect(ROLE_ATTR, content, (m) => m[1]);
+      const kbd = (content.match(KEYBOARD) || []).length;
+      const focus = (content.match(FOCUS_STATE) || []).length;
+      const landmarks = collect(LANDMARK, content, (m) => m[1]);
+      const skip = (content.match(SKIP_LINK) || []).length;
+      const imgs = collect(IMG_TAG, content, (m) => m[0]);
+
+      const families = [];
+      if (aria.length) families.push(['aria-attributes', 'ARIA attributes', { attributes: [...new Set(aria)].slice(0, 12) }]);
+      if (roles.length) families.push(['role-semantics', 'ARIA role semantics', { roles: [...new Set(roles)].slice(0, 12) }]);
+      if (kbd) families.push(['keyboard-support', 'Keyboard navigation', {}]);
+      if (focus) families.push(['focus-visible', 'Focus-visible states', {}]);
+      if (landmarks.length) families.push(['semantic-landmarks', 'Semantic landmarks', { landmarks: [...new Set(landmarks)] }]);
+      if (skip) families.push(['skip-link', 'Skip link', {}]);
+      if (imgs.length) {
+        const withAlt = imgs.filter((t) => /\balt\s*=/.test(t)).length;
+        families.push(['image-alt', 'Image alt coverage', { images: imgs.length, with_alt: withAlt }]);
+      }
+
+      for (const [key, name, extra] of families) {
+        const pid = addPattern(key, name, extra);
+        // The file *references* the a11y pattern.
+        addEdge(compId, pid, 'referenced-by', 0.5);
+        // The pattern is *documented-by* the WCAG criterion.
+        linkWcag(key, pid);
+      }
+    }
+  }
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    mapper: MAPPER,
+    generated_at: opts.generatedAt || '',
+    nodes: [...nodeMap.values()],
+    edges: [...edgeSet.values()],
+  };
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const roots = argv.length ? argv : [process.cwd()];
+  const fragment = extract(roots, { generatedAt: new Date().toISOString() });
+  process.stdout.write(JSON.stringify(fragment, null, 2) + '\n');
+}
+
+const invokedDirectly =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) main();