@hegemonart/get-design-done 1.30.5 → 1.30.6

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.30.6",
   "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",
@@ -88,7 +89,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([

package/scripts/lib/graph/atomic-write.mjs

@@ -0,0 +1,68 @@
+// scripts/lib/graph/atomic-write.mjs — Plan 30.6-02 Task 1
+//
+// Atomic JSON write seam per D-05: writeFile(tmp) + rename(tmp, target) in
+// the SAME directory (Windows atomicity guarantee — fs.rename is only
+// atomic across same-volume same-device renames). No proper-lockfile.
+// Single-writer assumption for the design pipeline; revisit in Phase 41
+// if multi-writer becomes a real need.
+
+import {
+  writeFileSync,
+  renameSync,
+  unlinkSync,
+  mkdirSync,
+  existsSync,
+} from 'node:fs';
+import { dirname, basename, join, resolve } from 'node:path';
+
+/**
+ * Atomically write a JSON payload to `target` using the tmp+rename pattern.
+ *
+ * Guarantees:
+ *   - Readers either see the previous file or the new file, never a
+ *     partial write.
+ *   - If rename fails, the tmp file is unlinked (no orphan tmp files).
+ *   - Tmp file lives in the SAME directory as target (Windows-safe).
+ *
+ * @param {string} target  - Absolute or repo-relative path to final file
+ * @param {unknown} payload - JSON-serializable value (stringified pretty 2-space)
+ */
+export function atomicWriteJson(target, payload) {
+  const parent = dirname(target);
+  const base = basename(target);
+  const tmp = join(
+    parent,
+    `.${base}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`,
+  );
+
+  // Defense per D-05: assert tmp is in same dir as target (cross-device
+  // rename is NOT atomic on Windows). Resolve both to normalize forward-
+  // vs back-slash separators on Windows so the comparison is path-shape-
+  // agnostic — string equality on dirname() outputs is fragile when the
+  // caller passes a POSIX-style path on Windows (`/tmp/foo`) and Node
+  // resolves it to a native-style temp dir (`C:\...\Temp\foo`).
+  if (resolve(dirname(tmp)) !== resolve(parent)) {
+    throw new Error(
+      `atomicWriteJson invariant: tmp not in same dir as target (tmp=${tmp}, target=${target})`,
+    );
+  }
+
+  mkdirSync(parent, { recursive: true });
+
+  const body = JSON.stringify(payload, null, 2) + '\n';
+
+  try {
+    writeFileSync(tmp, body, 'utf8');
+    renameSync(tmp, target);
+  } catch (err) {
+    // Clean up orphan tmp file on failure (best-effort).
+    if (existsSync(tmp)) {
+      try {
+        unlinkSync(tmp);
+      } catch {
+        // Swallow cleanup errors — original throw takes precedence.
+      }
+    }
+    throw err;
+  }
+}

package/scripts/lib/graph/build.mjs

@@ -0,0 +1,124 @@
+// scripts/lib/graph/build.mjs — Plan 30.6-02 Task 2
+//
+// buildGraph: read .design/intel/graph.json, transform per RESEARCH.md
+// intel→graph mapping, validate against schema 1.0, atomic-write to
+// .design/graph/graph.json. Deterministic when `now` is passed (test seam).
+
+import { readFileSync, existsSync } from 'node:fs';
+import { compileValidator, SCHEMA_VERSION } from './schema.mjs';
+import { atomicWriteJson } from './atomic-write.mjs';
+
+const DEFAULT_INTEL = '.design/intel/graph.json';
+const DEFAULT_OUT = '.design/graph/graph.json';
+const DEFAULT_BUILDER_VERSION = '1.30.6';
+const DEFAULT_SOURCE_MARKER = 'gdd-intel-store';
+
+/**
+ * Build .design/graph/graph.json from a .design/intel/graph.json slice.
+ *
+ * @param {object} opts
+ * @param {string} [opts.intelPath]      - default '.design/intel/graph.json'
+ * @param {string} [opts.outPath]        - default '.design/graph/graph.json'
+ * @param {string} [opts.builderVersion] - default '1.30.6'
+ * @param {string} [opts.now]            - ISO timestamp override (deterministic tests)
+ * @returns {{ok: true, nodeCount: number, edgeCount: number, outPath: string}}
+ * @throws on missing intel, parse failure, schema-invalid output
+ */
+export function buildGraph({
+  intelPath = DEFAULT_INTEL,
+  outPath = DEFAULT_OUT,
+  builderVersion = DEFAULT_BUILDER_VERSION,
+  now = undefined,
+} = {}) {
+  if (!existsSync(intelPath)) {
+    const err = new Error(`buildGraph: intel file not found at ${intelPath}`);
+    err.code = 'INTEL_MISSING';
+    throw err;
+  }
+
+  let intel;
+  try {
+    intel = JSON.parse(readFileSync(intelPath, 'utf8'));
+  } catch (e) {
+    const err = new Error(
+      `buildGraph: failed to parse intel JSON at ${intelPath}: ${e.message}`,
+    );
+    err.code = 'INTEL_PARSE_FAILED';
+    err.cause = e;
+    throw err;
+  }
+
+  const nodes = (Array.isArray(intel.nodes) ? intel.nodes : []).map(
+    (n) => transformNode(n),
+  );
+  const edges = (Array.isArray(intel.edges) ? intel.edges : []).map(
+    (e) => transformEdge(e),
+  );
+
+  const payload = {
+    schemaVersion: SCHEMA_VERSION,
+    metadata: {
+      generatedAt: now ?? new Date().toISOString(),
+      intelSource: intelPath,
+      nodeCount: nodes.length,
+      edgeCount: edges.length,
+      builderVersion,
+    },
+    nodes,
+    edges,
+  };
+
+  const validate = compileValidator();
+  if (!validate(payload)) {
+    const err = new Error('buildGraph: payload failed schema validation');
+    err.code = 'SCHEMA_INVALID';
+    err.schemaErrors = validate.errors;
+    throw err;
+  }
+
+  atomicWriteJson(outPath, payload);
+  return {
+    ok: true,
+    nodeCount: nodes.length,
+    edgeCount: edges.length,
+    outPath,
+  };
+}
+
+/**
+ * Intel → graph node transform per RESEARCH.md §Intel → graph transformation.
+ * intel.name → graph.label; any extra fields land in attrs blob.
+ */
+function transformNode(n) {
+  if (!n || typeof n !== 'object') return n;
+  // Pull off named intel fields; spread rest into attrs (lenient passthrough).
+  const { id, type, name, label, attrs, source, ...rest } = n;
+  const out = { id, type };
+  // Honor explicit label first; fall back to intel.name; otherwise omit.
+  const labelOut = label ?? name;
+  if (labelOut !== undefined) out.label = labelOut;
+  // Merge intel-extra fields into attrs (existing attrs win).
+  const restKeys = Object.keys(rest);
+  if (attrs || restKeys.length) {
+    out.attrs = { ...rest, ...(attrs || {}) };
+  }
+  out.source = source ?? DEFAULT_SOURCE_MARKER;
+  return out;
+}
+
+/**
+ * Intel → graph edge transform. Edges already use {from,to,kind} verbatim
+ * per D-03.b — pure passthrough plus attrs absorption.
+ */
+function transformEdge(e) {
+  if (!e || typeof e !== 'object') return e;
+  const { from, to, kind, weight, attrs, source, ...rest } = e;
+  const out = { from, to, kind };
+  if (typeof weight === 'number') out.weight = weight;
+  const restKeys = Object.keys(rest);
+  if (attrs || restKeys.length) {
+    out.attrs = { ...rest, ...(attrs || {}) };
+  }
+  out.source = source ?? DEFAULT_SOURCE_MARKER;
+  return out;
+}

package/scripts/lib/graph/diff.mjs

@@ -0,0 +1,90 @@
+// scripts/lib/graph/diff.mjs — Plan 30.6-02 Task 2
+//
+// diffGraph: compare two graph.json files, emit {addedNodes, removedNodes,
+// changedNodes, addedEdges, removedEdges}. Node identity = .id; edge
+// identity = `${from}::${to}::${kind}` per upstream-key formula.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { isDeepStrictEqual } from 'node:util';
+import { compileValidator } from './schema.mjs';
+
+/**
+ * Diff two graphs by file path.
+ *
+ * @param {object} opts
+ * @param {string} opts.fromPath - baseline graph path
+ * @param {string} opts.toPath   - current graph path
+ * @returns {{addedNodes: any[], removedNodes: any[], changedNodes: Array<{id:string, before:any, after:any}>, addedEdges: any[], removedEdges: any[]}}
+ */
+export function diffGraph({ fromPath, toPath } = {}) {
+  if (!fromPath || !toPath) {
+    const err = new Error('diffGraph: fromPath and toPath are required');
+    err.code = 'DIFF_ARGS_MISSING';
+    throw err;
+  }
+  const from = readAndValidate(fromPath, 'fromPath');
+  const to = readAndValidate(toPath, 'toPath');
+
+  const fromNodeMap = new Map(from.nodes.map((n) => [n.id, n]));
+  const toNodeMap = new Map(to.nodes.map((n) => [n.id, n]));
+
+  const addedNodes = [];
+  const removedNodes = [];
+  const changedNodes = [];
+
+  for (const [id, after] of toNodeMap) {
+    if (!fromNodeMap.has(id)) {
+      addedNodes.push(after);
+    } else {
+      const before = fromNodeMap.get(id);
+      if (!isDeepStrictEqual(before, after)) {
+        changedNodes.push({ id, before, after });
+      }
+    }
+  }
+  for (const [id, before] of fromNodeMap) {
+    if (!toNodeMap.has(id)) removedNodes.push(before);
+  }
+
+  const edgeKey = (e) => `${e.from}::${e.to}::${e.kind}`;
+  const fromEdgeMap = new Map(from.edges.map((e) => [edgeKey(e), e]));
+  const toEdgeMap = new Map(to.edges.map((e) => [edgeKey(e), e]));
+
+  const addedEdges = [];
+  const removedEdges = [];
+  for (const [k, e] of toEdgeMap) if (!fromEdgeMap.has(k)) addedEdges.push(e);
+  for (const [k, e] of fromEdgeMap) if (!toEdgeMap.has(k)) removedEdges.push(e);
+
+  return {
+    addedNodes,
+    removedNodes,
+    changedNodes,
+    addedEdges,
+    removedEdges,
+  };
+}
+
+function readAndValidate(path, label) {
+  if (!existsSync(path)) {
+    const err = new Error(`diffGraph: ${label} not found at ${path}`);
+    err.code = 'DIFF_FILE_MISSING';
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (e) {
+    const err = new Error(`diffGraph: ${label} parse failed: ${e.message}`);
+    err.code = 'DIFF_PARSE_FAILED';
+    err.cause = e;
+    throw err;
+  }
+  const validate = compileValidator();
+  if (!validate(parsed)) {
+    const err = new Error(`diffGraph: ${label} failed schema validation`);
+    err.code = 'DIFF_SCHEMA_INVALID';
+    err.schemaErrors = validate.errors;
+    throw err;
+  }
+  return parsed;
+}

package/scripts/lib/graph/index.mjs

@@ -0,0 +1,14 @@
+// scripts/lib/graph/index.mjs — Plan 30.6-02 Task 2
+//
+// Barrel re-export for graph subcommand handlers. 30.6-03 layers query,
+// upsertNode, upsertEdge on top of these exports + the schema/atomic-write
+// foundation; 30.6-04 verifies the union decouples from upstream GSD.
+
+export { buildGraph } from './build.mjs';
+export { statusGraph } from './status.mjs';
+export { diffGraph } from './diff.mjs';
+export { compileValidator, SCHEMA_VERSION, SCHEMA } from './schema.mjs';
+export { atomicWriteJson } from './atomic-write.mjs';
+export { queryGraph } from './query.mjs';                  // 30.6-03 Task 1
+export { estimateTokens } from './token-estimate.mjs';     // 30.6-03 Task 1
+export { upsertNode, upsertEdge } from './upsert.mjs';     // 30.6-03 Task 2