@hegemonart/get-design-done 1.30.5 → 1.31.0

package/connections/graphify.md

@@ -1,46 +1,43 @@
 # Graphify — Connection Specification
 
-This file is the connection specification for Graphify within the get-design-done pipeline. Graphify builds a queryable knowledge graph over the codebase — mapping component↔token↔decision relationships via Tree-sitter static analysis and LLM semantic extraction. See `connections/connections.md` for the full connection index and capability matrix.
+This file is the connection specification for **Graphify** within the get-design-done pipeline. Graphify builds a queryable knowledge graph over the codebase and design intel — mapping component↔token↔decision relationships from `.design/intel/` slices. See `connections/connections.md` for the full connection index and capability matrix.
+
+> **Native, no external dependency.** Phase 30.6 (v1.30.6) replaced the previous runtime dispatch to `~/.claude/get-shit-done/bin/gsd-tools.cjs graphify *` with a native CLI shipped in this repo at `bin/gdd-graph`. No Python, no separate install — just Node ≥22.
 
 ---
 
 ## Setup
 
 **Prerequisites:**
-- Python 3.9+ available on PATH
-- GSD framework with `graphify.enabled = true` in `.planning/config.json`
+- Node ≥22 (per `package.json` engines)
+- get-design-done installed (provides `bin/gdd-graph`)
 
-**Install:**
-```
-pip install graphifyy
-graphify install        # installs skill files into ~/.claude/skills/graphify/
-```
+**Enable in project config** (per D-09 — direct file edit, no CLI subcommand):
 
-**Enable in GSD config:**
-```
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-set graphify.enabled true
+Edit `.design/config.json` and set:
+```json
+{
+  "graphify": {
+    "enabled": true
+  }
+}
 ```
 
-**Build the graph (initial):**
-```
-graphify .              # run in project root; produces graphify-out/graph.json
-# or via GSD tools:
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify build
-```
+If `.design/config.json` does not exist, create it. Missing file = disabled.
 
-**Recommended: auto-rebuild after commits:**
+**Build the graph (initial):**
 ```
-graphify hook install
+node bin/gdd-graph build
 ```
+Produces `.design/graph/graph.json` (Ajv-validated against `scripts/lib/graph/schema.json`).
 
 **Verification:**
-After building, run:
 ```
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify status
+node bin/gdd-graph status --format json
 ```
-Expect: `{ enabled: true, graph_path: "...", node_count: N, edge_count: N, stale: false }`
+Expect: `{ configured: true, exists: true, node_count: N, edge_count: M, built_at: "<iso>", schema_version: "1.0" }`.
 
-**Note:** Graphify is an optional external dependency. It requires Python and takes 1-5 minutes to build on a large codebase. Do NOT add to plugin bootstrap — users opt in manually.
+**Note:** Graphify is optional. It is a pre-search oracle for planner and verifier agents, never a hard requirement. All stages MUST degrade gracefully when graphify is `unavailable` or `not_configured`.
 
 ---
 
@@ -50,7 +47,7 @@ Expect: `{ enabled: true, graph_path: "...", node_count: N, edge_count: N, stale
 
 | Node type | Source | ID pattern |
 |-----------|--------|-----------|
-| component | `.stories.tsx` / `src/components/*.tsx` | `component:<name>` |
+| component | `.stories.tsx` / `src/components/*.tsx` (via intel slices) | `component:<name>` |
 | token:color | CSS custom properties / Figma variables | `token:color/<name>` |
 | token:spacing | CSS custom properties | `token:spacing/<name>` |
 | token:typography | CSS custom properties | `token:typography/<name>` |
@@ -65,7 +62,7 @@ Expect: `{ enabled: true, graph_path: "...", node_count: N, edge_count: N, stale
 
 ### Edge Types
 
-| Edge | From | To | Meaning |
+| Edge kind | From | To | Meaning |
 |------|------|-----|---------|
 | `uses` | component | token | Component references this token |
 | `renders` | page | component | Page renders this component |
@@ -74,22 +71,32 @@ Expect: `{ enabled: true, graph_path: "...", node_count: N, edge_count: N, stale
 | `maps-to` | figma-variable | token | Figma variable corresponds to CSS token |
 | `detected-at` | anti-pattern | component | Anti-pattern found in this component |
 
-### graph.json structure
+### graph.json structure (schema v1.0)
 
 ```json
 {
+  "schema_version": "1.0",
+  "built_at": "2026-05-28T12:00:00.000Z",
   "nodes": [
-    { "id": "component:Button", "label": "Button", "type": "component",
-      "description": "Primary interactive element", "source": "src/components/Button.tsx" }
+    {
+      "id": "component:Button",
+      "type": "component",
+      "label": "Button",
+      "attrs": { "source": "src/components/Button.tsx" }
+    }
   ],
   "edges": [
-    { "source": "component:Button", "target": "token:color/primary/500",
-      "label": "uses", "confidence": "EXTRACTED", "confidence_score": 0.95 }
+    {
+      "from": "component:Button",
+      "to": "token:color/primary/500",
+      "kind": "uses",
+      "weight": 0.95
+    }
   ]
 }
 ```
 
-Edge confidence tiers: EXTRACTED (found in source), INFERRED (semantic inference), AMBIGUOUS (flagged for review).
+Edges use the `{from, to, kind, weight?}` shape (per D-03.b — matches intel-store schema verbatim, no translation layer). The optional `weight: number` replaces the upstream three-tier confidence enum (per D-03.c).
 
 ---
 
@@ -110,18 +117,19 @@ Unlike MCP connections, Graphify has no ToolSearch check. The probe is file-exis
 
 **Graphify probe sequence (execute at agent entry, before using graph):**
 
-Step G1 — Config check:
+Step G1 — Config check (per D-09 — direct read, no CLI subcommand):
 ```
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify status
-→ Error or { enabled: false }  → graphify: not_configured  (skip all graph steps)
-→ { enabled: true }            → proceed to Step G2
+node -e "try{const c=JSON.parse(require('fs').readFileSync('.design/config.json','utf8'));process.stdout.write(String(c.graphify?.enabled===true))}catch{process.stdout.write('false')}"
+→ false → graphify: not_configured  (skip all graph steps)
+→ true  → proceed to Step G2
 ```
 
-Step G2 — Graph file check:
+Step G2 — Graph status check (native CLI):
 ```
-Check if graphify-out/graph.json exists in project root
-→ Absent                       → graphify: unavailable  (graph not built yet)
-→ Present                      → graphify: available
+node bin/gdd-graph status --format json
+→ { configured: true, exists: true }  → graphify: available
+→ { configured: true, exists: false } → graphify: unavailable  (graph not built yet)
+→ { configured: false, ... }          → graphify: not_configured  (mirrors G1; defensive)
 ```
 
 Write graphify status to `.design/STATE.md` `<connections>`.
@@ -138,8 +146,8 @@ This is the canonical pre-search pattern for agents. Copy inline — SKILL.md an
 
 Step 1: Query graph for decision node and its neighbors
 ```
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify query "decision:D-<nn>" --budget 1500
-→ Returns: connected components + tokens as JSON
+node bin/gdd-graph query "decision:D-<nn>" --budget 1500
+→ Returns: ranked match list — connected components + tokens as JSON
 → Use returned component IDs as grep seed list (reduces false-negative "not found")
 ```
 
@@ -150,15 +158,15 @@ Step 2: Grep each returned component for the decision pattern
 
 Step 1: Query graph for token node and its neighbors
 ```
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify query "<token-name>" --budget 1500
-→ Returns: all components that reference this token
+node bin/gdd-graph query "<token-name>" --budget 1500
+→ Returns: all components that reference this token (ranked by D-04.a score)
 → Annotate planned task with "N components affected" before scoping
 ```
 
 Step 2: Include component list in the task description
 (then continue standard planning behavior)
 
-**Budget note:** Use `--budget 1500` for pre-search queries. High confidence_score edges (>= 0.8) are more reliable; AMBIGUOUS edges are hints only.
+**Budget note:** Use `--budget 1500` for pre-search queries. Higher-weight edges (`weight >= 0.8`) are more reliable; lower-weight edges are hints only.
 
 ---
 
@@ -177,21 +185,24 @@ The graph is a performance optimization and accuracy enhancer. It is never a har
 ## Anti-Patterns
 
 - **Do NOT use graphify to replace grep.** The graph is a seed list, not a complete index. Always grep after querying the graph.
-- **Do NOT embed graph.json contents in agent context.** Query specific nodes via gsd-tools; never read graph.json directly.
+- **Do NOT embed `graph.json` contents in agent context.** Query specific nodes via `bin/gdd-graph query`; never read `graph.json` directly.
 - **Do NOT query the graph during scan or design stages.** The graph is read-only and only useful when decisions already exist (plan, verify).
-- **Do NOT block on graph build time.** If `graphify build` takes >30 seconds mid-session, log "graphify build deferred — run /gdd:graphify build manually" and continue without graph.
-- **Do NOT assume graph covers .design/ artifacts.** Graphify analyzes source code (src/, components/). DESIGN-CONTEXT.md and DESIGN-PLAN.md are not graph nodes unless explicitly indexed.
+- **Do NOT block on graph build time.** If `gdd-graph build` takes >30 seconds mid-session, log "graphify build deferred — run /gdd:graphify build manually" and continue without graph.
+- **Do NOT assume graph covers `.design/` artifacts.** The build walks `.design/intel/` slices and project source; arbitrary planning docs are not graph nodes unless explicitly indexed.
 
 ---
 
 ## /gdd:graphify Commands
 
-| Subcommand | GSD tools call | Purpose |
+| Subcommand | Native CLI call | Purpose |
 |------------|----------------|---------|
-| `build` | `gsd-tools graphify build` | Build or rebuild the knowledge graph |
-| `query <term>` | `gsd-tools graphify query "<term>" --budget 2000` | Query the graph for a node and its neighbors |
-| `status` | `gsd-tools graphify status` | Check graph age, node count, enabled status |
-| `diff` | `gsd-tools graphify diff` | Show topology changes since last build |
+| `build` | `node bin/gdd-graph build` | Build or rebuild the knowledge graph |
+| `query <term>` | `node bin/gdd-graph query "<term>" --budget 2000` | Query the graph for a node and its neighbors |
+| `status` | `node bin/gdd-graph status` | Check graph age, node count, enabled status |
+| `diff` | `node bin/gdd-graph diff` | Show topology changes since last build |
+| `upsert-node` | `node bin/gdd-graph upsert-node --id X --type T --label L` | Programmatic single-node insert (used by gdd-graph-refresh agent) |
+| `upsert-edge` | `node bin/gdd-graph upsert-edge --from A --to B --kind R` | Programmatic single-edge insert (used by gdd-graph-refresh agent) |
+
+If `graphify.enabled` is `false` (or `.design/config.json` is missing), the `bin/gdd-graph` subcommands graceful-degrade — `status` returns `{ configured: false, exists: false }`, other subcommands no-op with exit 0 and a one-line stderr notice.
 
-If `graphify.enabled = false` in `.planning/config.json`, the skill prompts:
-"Graphify is not enabled. Enable with: gsd-tools config-set graphify.enabled true — then run /gdd:graphify build."
+To enable: edit `.design/config.json` and set `graphify.enabled: true`, then `node bin/gdd-graph build`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.30.5",
+  "version": "1.31.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -28,6 +28,7 @@
   ],
   "bin": {
     "gdd-events": "./scripts/cli/gdd-events.mjs",
+    "gdd-graph": "./bin/gdd-graph",
     "gdd-mcp": "./scripts/mcp-servers/gdd-mcp/server.ts",
     "gdd-sdk": "./bin/gdd-sdk",
     "gdd-state-mcp": "./scripts/mcp-servers/gdd-state/server.ts",
@@ -79,7 +80,10 @@
     "gemini",
     "mcp",
     "parallel-agents",
-    "agent-sdk"
+    "agent-sdk",
+    "figma",
+    "extractor",
+    "design-system-sync"
   ],
   "skills": [
     "SKILL.md"
@@ -88,7 +92,8 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.143",
     "@clack/prompts": "^1.2.0",
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ajv": "^8.18.0"
   },
   "optionalDependencies": {
     "pngjs": "^7.0.0",

package/reference/capability-gap-stage-gate.md

@@ -159,10 +159,13 @@ appends the following verbatim block to the cycle markdown:
 > opt in with the project-local command below. You can always opt out
 > later by deleting the timestamps from `.design/config.json` (§ 7).
 >
-> <!-- TODO: confirm opt-in command — likely
->      `node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config set capability_gap_gate.opted_in_at "$(date -Iseconds)"`
->      or a project-local equivalent. Plan 29-05 (apply-reflections
->      extension) will land the canonical command. -->
+> <!-- Phase 30.6 (D-09) update: per the convention adopted across the
+>      knowledge layer in v1.30.6, project-local config flips are direct
+>      edits to .design/config.json — no CLI subcommand. The canonical
+>      opt-in is therefore: edit .design/config.json to add
+>      { "capability_gap_gate": { "opted_in_at": "<ISO date>" } }.
+>      Plan 29-05 (apply-reflections extension) surfaces this as a guided
+>      prompt rather than a CLI invocation. -->
 >
 > This prompt is emitted at most once per project. If you ignore it,
 > the gate continues to evaluate every cycle but does not re-prompt

package/reference/model-tiers.md

@@ -13,7 +13,7 @@ Phase 10.1 (OPT-06) locked the initial per-agent tier assignment. Phase 11's `de
 Pick `haiku` when the agent is:
 - Applying a fixed scoring rubric (`design-verifier` runs five deterministic passes with numeric category scores).
 - Producing a boolean + rationale answer (`design-plan-checker`, `design-context-checker`, `design-integration-checker` all return "gaps found" + structured list).
-- Performing a read-only state sync (`gdd-graphify-sync` mirrors graph state — no reasoning density beyond schema matching).
+- Performing a read-only state sync (`gdd-graph-refresh` mirrors graph state — no reasoning density beyond schema matching).
 - Running at high frequency where cost compounds (checkers run on every `/gdd:verify` pass — cost multiplies with iterations).
 
 Haiku's ~20x price advantage over Opus per 1M tokens (see `reference/model-prices.md`) makes it correct for deterministic-rubric work where the marginal quality gain of larger models is negligible.
@@ -49,7 +49,7 @@ Opus cost (~5x Sonnet, ~25x Haiku) is justified only when a single wrong decisio
 | design-plan-checker | Checker | haiku | Checks the plan against a fixed schema — boolean + gap-list output. |
 | design-context-checker | Checker | haiku | Checks context completeness against a schema — boolean + gap-list output. |
 | design-integration-checker | Checker | haiku | Checks cross-artifact references — deterministic link-integrity work. |
-| gdd-graphify-sync | Sync agent | haiku | Mirrors graph state to the graph store — no reasoning density required. |
+| gdd-graph-refresh | Refresh agent | haiku | Rebuilds graph at .design/graph/graph.json from intel slices — no reasoning density required. |
 | a11y-mapper | Mapper | sonnet | Open-ended a11y pattern recognition across many files; Sonnet's breadth matters. |
 | component-taxonomy-mapper | Mapper | sonnet | Classifies components by role — requires nuance Haiku lacks, not enough to warrant Opus. |
 | design-auditor | Worker | sonnet | Emits structured findings from code inspection; Sonnet balances depth with cost. |

package/reference/start-interview.md

@@ -2,7 +2,7 @@
 
 **Purpose:** collect the minimum signal needed to steer the findings engine without slowing first-run completion past 30 seconds of interview wall-clock. Autodetectable dimensions collapse to a one-key confirmation; genuinely non-derivable dimensions are asked explicitly.
 
-**Hard constraint:** v1.14.7 ships this fixed question set. Do not branch, re-order, or insert new questions without an explicit `/gsd-discuss-phase` override captured in a future DISCUSSION.md.
+**Hard constraint:** v1.14.7 ships this fixed question set. Do not branch, re-order, or insert new questions without an explicit `/gdd:discuss` override captured in a future DISCUSSION.md.
 
 ---
 

package/scripts/detect-stale-refs.cjs

@@ -19,6 +19,12 @@ const DEPRECATIONS_PATH = path.join(REPO_ROOT, 'reference/DEPRECATIONS.md');
 // would over-fire. Cover those cases via targeted review rather than grep.
 const PATTERNS = [
   { name: '/design: namespace (replaced by /gdd:)', regex: /\/design:[a-z-]+/g },
+  // Phase 30.6: runtime dispatch to upstream gsd-tools.cjs is now disallowed.
+  // Native CLI lives at bin/gdd-graph (graph ops) and is invoked as `node bin/gdd-graph <sub>`.
+  // The pattern is precise — only the explicit bash dispatch is flagged. Prose mentions
+  // of "gsd-tools" or "get-shit-done" in attribution contexts (NOTICE, CHANGELOG, README)
+  // are NOT matched because they don't include the leading `node "$HOME/.claude/...` token.
+  { name: 'gsd-tools.cjs runtime dispatch (use bin/gdd-graph instead)', regex: /node\s+["']?\$HOME\/\.claude\/get-shit-done\/bin\/gsd-tools\.cjs/g },
 ];
 
 const EXCLUDE_DIRS = new Set([