@hegemonart/get-design-done 1.51.0 → 1.53.0

package/scripts/lib/design-context/merge-fragments.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+// scripts/lib/design-context/merge-fragments.mjs — Phase 52 (DesignContext graph), executor B.
+//
+// Deterministic, dependency-free fragment merger. Reads N mapper Fragments
+// (schema_version 52.0) and produces the single merged Graph
+// (schema_version 52.0, NO `mapper` field) written atomically to disk.
+//
+// Merge rules
+// -----------
+// NODES — deduped by `id`:
+//   - tags          : union (order-stable, de-duplicated)
+//   - summary       : prefer the first NON-STUB summary (non-empty) seen; an
+//                     empty-string summary is a stub the LLM phase fills later
+//   - complexity    : prefer the first non-'moderate' value (the stub default)
+//   - other fields  : first-writer-wins, but later non-empty values fill gaps
+//                     left empty/absent by the first writer (e.g. value, layer,
+//                     subtype). type/name keep the first non-empty.
+//
+// EDGES — deduped by (source,target,type); for each edge we verify BOTH
+// endpoints resolve to a node id that exists in SOME fragment (the merged node
+// set):
+//   - both endpoints resolve  -> keep the edge (this is cross-fragment
+//                                "recovery": the a11y fragment can reference a
+//                                component:* node defined only in the component
+//                                fragment, and the edge survives the merge);
+//   - an endpoint is missing  -> DROP the edge and report it. A missing
+//                                endpoint cannot be recovered (no node with that
+//                                id exists in any fragment), so the edge is
+//                                truly dangling.
+//
+// "Could not fix" items (dropped dangling edges; any unresolved id) are written
+// to stderr, one per line, prefixed `could-not-fix:`.
+//
+// Public API:
+//   merge(fragments) -> { graph, couldNotFix: string[] }   (pure)
+//   main()           -> reads argv globs / .design/fragments/*.json, atomic-writes graph
+//
+// No network, no deps beyond the sibling atomic-write helper, no top-level
+// Date.now() (stamped in main()).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { atomicWriteJson } from '../graph/atomic-write.mjs';
+
+const SCHEMA_VERSION = '52.0';
+const DEFAULT_OUT = path.join('.design', 'context-graph.json');
+const DEFAULT_FRAGMENT_DIR = path.join('.design', 'fragments');
+
+const STUB_COMPLEXITY = 'moderate';
+const NODE_RESERVED = new Set(['id', 'type', 'name', 'summary', 'tags', 'complexity']);
+
+function isNonStubSummary(s) {
+  return typeof s === 'string' && s.trim().length > 0;
+}
+
+/** Merge one node into the accumulator map (dedupe by id). */
+function mergeNode(map, node) {
+  if (!node || typeof node.id !== 'string') return;
+  const existing = map.get(node.id);
+  if (!existing) {
+    // Clone so we never mutate the caller's input objects.
+    map.set(node.id, {
+      id: node.id,
+      type: node.type,
+      name: node.name,
+      summary: isNonStubSummary(node.summary) ? node.summary : '',
+      tags: Array.isArray(node.tags) ? [...new Set(node.tags)] : [],
+      complexity: node.complexity || STUB_COMPLEXITY,
+      ...copyExtras({}, node),
+    });
+    return;
+  }
+
+  // tags: union, order-stable.
+  if (Array.isArray(node.tags) && node.tags.length) {
+    const seen = new Set(existing.tags);
+    for (const t of node.tags) if (!seen.has(t)) { existing.tags.push(t); seen.add(t); }
+  }
+  // summary: first non-stub wins.
+  if (!isNonStubSummary(existing.summary) && isNonStubSummary(node.summary)) {
+    existing.summary = node.summary;
+  }
+  // complexity: first non-default ('moderate' is the stub) wins.
+  if (existing.complexity === STUB_COMPLEXITY && node.complexity && node.complexity !== STUB_COMPLEXITY) {
+    existing.complexity = node.complexity;
+  }
+  // type/name: fill if the first writer left them empty.
+  if (!existing.type && node.type) existing.type = node.type;
+  if (!existing.name && node.name) existing.name = node.name;
+  // extras: fill gaps the first writer did not set.
+  copyExtras(existing, node, /* fillOnly */ true);
+}
+
+/** Copy non-reserved fields from `node` onto `target`. */
+function copyExtras(target, node, fillOnly = false) {
+  for (const k of Object.keys(node)) {
+    if (NODE_RESERVED.has(k)) continue;
+    if (fillOnly && target[k] !== undefined && target[k] !== '' && target[k] !== null) continue;
+    target[k] = node[k];
+  }
+  return target;
+}
+
+/**
+ * Pure merge.
+ * @param {object[]} fragments  array of Fragment objects (each {nodes[], edges[]})
+ * @returns {{graph: object, couldNotFix: string[]}}
+ */
+export function merge(fragments) {
+  const list = Array.isArray(fragments) ? fragments : [fragments];
+  const nodeMap = new Map();
+  const couldNotFix = [];
+
+  // Pass 1: union all nodes (so edge recovery can see ids from any fragment).
+  for (const frag of list) {
+    if (!frag || !Array.isArray(frag.nodes)) continue;
+    for (const n of frag.nodes) mergeNode(nodeMap, n);
+  }
+
+  // Pass 2: dedupe + validate edges against the merged node set.
+  const edgeMap = new Map();
+  for (const frag of list) {
+    if (!frag || !Array.isArray(frag.edges)) continue;
+    for (const e of frag.edges) {
+      if (!e || typeof e.source !== 'string' || typeof e.target !== 'string' || !e.type) {
+        couldNotFix.push(`could-not-fix: malformed edge ${JSON.stringify(e)}`);
+        continue;
+      }
+      const srcOk = nodeMap.has(e.source);
+      const dstOk = nodeMap.has(e.target);
+      if (!srcOk || !dstOk) {
+        // Truly dangling — no node with that id exists in ANY fragment.
+        const missing = [!srcOk ? `source=${e.source}` : null, !dstOk ? `target=${e.target}` : null]
+          .filter(Boolean).join(' ');
+        couldNotFix.push(`could-not-fix: dropped dangling edge (${e.type}) ${missing}`);
+        continue;
+      }
+      // Recovered (or always-resolved) — keep, deduped by (source,target,type).
+      const key = `${e.source}--${e.type}-->${e.target}`;
+      if (!edgeMap.has(key)) {
+        edgeMap.set(key, {
+          source: e.source,
+          target: e.target,
+          type: e.type,
+          direction: e.direction || 'forward',
+          weight: typeof e.weight === 'number' ? e.weight : 0.5,
+        });
+      } else if (typeof e.weight === 'number') {
+        // Keep the max weight when the same edge appears in two fragments.
+        const cur = edgeMap.get(key);
+        if (e.weight > cur.weight) cur.weight = e.weight;
+      }
+    }
+  }
+
+  const graph = {
+    schema_version: SCHEMA_VERSION,
+    generated_at: '',
+    nodes: [...nodeMap.values()],
+    edges: [...edgeMap.values()],
+  };
+  return { graph, couldNotFix };
+}
+
+// ---------------------------------------------------------------------------
+// CLI helpers.
+// ---------------------------------------------------------------------------
+
+/** Resolve argv into a concrete list of fragment file paths. */
+function resolveInputs(argv) {
+  // argv shape: [...inputs?] [--out <path>]
+  const args = [...argv];
+  let out = DEFAULT_OUT;
+  const inputs = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--out' || args[i] === '-o') { out = args[++i] || out; continue; }
+    inputs.push(args[i]);
+  }
+
+  let files = [];
+  if (inputs.length) {
+    for (const inp of inputs) {
+      let st;
+      try { st = fs.statSync(inp); } catch { continue; }
+      if (st.isDirectory()) {
+        for (const f of fs.readdirSync(inp)) if (f.endsWith('.json')) files.push(path.join(inp, f));
+      } else if (st.isFile()) {
+        files.push(inp);
+      }
+    }
+  } else if (fs.existsSync(DEFAULT_FRAGMENT_DIR)) {
+    for (const f of fs.readdirSync(DEFAULT_FRAGMENT_DIR)) {
+      if (f.endsWith('.json')) files.push(path.join(DEFAULT_FRAGMENT_DIR, f));
+    }
+  }
+  files = [...new Set(files)].sort(); // deterministic order
+  return { files, out };
+}
+
+function readFragment(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    process.stderr.write(`could-not-fix: unreadable fragment ${file} (${err.message})\n`);
+    return null;
+  }
+}
+
+/** CLI entry: read fragments, merge, stamp generated_at, atomic-write graph. */
+export function main(argv = process.argv.slice(2)) {
+  const { files, out } = resolveInputs(argv);
+  const fragments = files.map(readFragment).filter(Boolean);
+  const { graph, couldNotFix } = merge(fragments);
+  graph.generated_at = new Date().toISOString();
+
+  for (const line of couldNotFix) process.stderr.write(line + '\n');
+
+  atomicWriteJson(out, graph);
+  process.stderr.write(
+    `merged ${fragments.length} fragment(s) -> ${out} (${graph.nodes.length} nodes, ${graph.edges.length} edges, ${couldNotFix.length} could-not-fix)\n`,
+  );
+}
+
+const invokedDirectly =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) main();

package/scripts/lib/explore-parallel-runner/index.ts

@@ -26,6 +26,10 @@ import { resolve as resolvePath } from 'node:path';
 
 import { getLogger } from '../logger/index.ts';
 import { resolveConcurrency } from '../parallelism-engine/concurrency-tuner.cjs';
+// Phase 53 (DISC-01): the incremental batching composer. CJS, imported the same
+// way as concurrency-tuner.cjs above. Only invoked when opts.incremental.graph
+// is supplied — the default explore path never loads its ESM/TS dependencies.
+import { planIncremental } from '../mappers/incremental-discover.cjs';
 
 import {
   isParallelismSafe,
@@ -130,6 +134,58 @@ export async function run(
 
   const outputPath: string = resolvePath(cwd, '.design/DESIGN-PATTERNS.md');
 
+  // --- Phase 53 (DISC-01): incremental batching ----------------------------
+  //
+  // ONLY runs when a Phase-52 graph is supplied. Groups the graph into Louvain
+  // community batches, runs the change classifier against the prior fingerprint
+  // snapshot, and elects which batches to re-map (SKIP=0, PARTIAL=affected,
+  // FULL=all). The result rides on `batching`; the spec roster + rolling
+  // semaphore below are UNCHANGED. Backward-compatible: absent graph ⇒ undefined
+  // batching ⇒ the Phase-21 path is byte-for-byte the same. Never throws —
+  // batching is advisory metadata, and a planning failure must not abort mappers.
+  let batching: ExploreRunnerResult['batching'] = undefined;
+  if (opts.incremental && opts.incremental.graph !== undefined && opts.incremental.graph !== null) {
+    try {
+      const plan = await planIncremental({
+        graph: opts.incremental.graph,
+        prevFingerprints: opts.incremental.prevFingerprints,
+        opts: {
+          ...(opts.incremental.forceFull !== undefined ? { forceFull: opts.incremental.forceFull } : {}),
+          ...(opts.incremental.computeBatchesOpts !== undefined ? { computeBatchesOpts: opts.incremental.computeBatchesOpts } : {}),
+          ...(opts.incremental.neighborCap !== undefined ? { neighborCap: opts.incremental.neighborCap } : {}),
+          ...(opts.incremental.thresholds !== undefined ? { thresholds: opts.incremental.thresholds } : {}),
+        },
+      });
+      batching = Object.freeze({
+        action: plan.action,
+        method: plan.method,
+        modularity: plan.modularity,
+        batches: Object.freeze(plan.batches.map((b: { id: string; members: string[]; mergeable: boolean; kind: string; source: string }) => Object.freeze({
+          id: b.id,
+          members: Object.freeze([...b.members]),
+          mergeable: b.mergeable,
+          kind: b.kind,
+          source: b.source,
+        }))),
+        batchesToMap: Object.freeze(plan.batchesToMap.map((b: { id: string }) => b.id)),
+        neighborMaps: Object.freeze({ ...plan.neighborMaps }),
+        classification: Object.freeze({ ...plan.classification }),
+      });
+      logger.info('explore.runner.batching', {
+        action: plan.action,
+        method: plan.method,
+        batch_count: plan.batches.length,
+        batches_to_map: plan.batchesToMap.length,
+        structural_count: plan.classification.structuralCount,
+      });
+    } catch (err) {
+      // Planning failure degrades to "no batching" — the mappers still run.
+      const message: string = err instanceof Error ? err.message : String(err);
+      logger.warn('explore.runner.batching_failed', { message });
+      batching = undefined;
+    }
+  }
+
   logger.info('explore.runner.started', {
     mapper_count: specs.length,
     concurrency,
@@ -154,6 +210,7 @@ export async function run(
       parallel_count: 0,
       serial_count: 0,
       total_usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+      ...(batching !== undefined ? { batching } : {}),
     });
   }
 
@@ -294,5 +351,6 @@ export async function run(
       output_tokens: totalOutput,
       usd_cost: totalCost,
     },
+    ...(batching !== undefined ? { batching } : {}),
   });
 }

package/scripts/lib/explore-parallel-runner/types.ts

@@ -109,6 +109,35 @@ export interface ExploreRunnerOptions {
   readonly pollIntervalMs?: number;
   /** Override the file-watch timeout (ms). Default 600_000 (10 min). */
   readonly timeoutMs?: number;
+  /**
+   * Phase 53 (DISC-01) — OPTIONAL incremental batching. When supplied with a
+   * Phase-52 DesignContext `graph`, the runner runs the change classifier
+   * (`scripts/lib/mappers/incremental-discover.cjs#planIncremental`) FIRST,
+   * groups the graph into Louvain community batches, attaches a per-batch
+   * neighborMap sidecar, and dispatches only the batches the classifier elects
+   * to re-map (SKIP=0, PARTIAL=affected, FULL=all). The mapper SPEC roster is
+   * unchanged — batching is metadata threaded onto the result so the explore
+   * stage can scope each mapper to its community; the rolling semaphore still
+   * spawns the spec roster at the tuned concurrency.
+   *
+   * BACKWARD-COMPATIBLE: when `incremental` is absent (or `graph` is missing),
+   * the runner behaves EXACTLY as before — no batching, no classifier, the
+   * Phase-21 partition-then-spawn path runs untouched.
+   */
+  readonly incremental?: {
+    /** Phase-52 DesignContext graph ({ nodes, edges }). Required to batch. */
+    readonly graph: unknown;
+    /** Prior fingerprint snapshot (store.readCurrent().fingerprints). Absent ⇒ bootstrap ⇒ FULL. */
+    readonly prevFingerprints?: unknown;
+    /** The `--full` opt-out: force a FULL re-map regardless of the classifier. */
+    readonly forceFull?: boolean;
+    /** Forwarded to computeBatches (resolution, maxCommunitySize, configCwd, …). */
+    readonly computeBatchesOpts?: unknown;
+    /** buildNeighborMap cap (default 50). */
+    readonly neighborCap?: number;
+    /** Forwarded into classify's projectStats.thresholds. */
+    readonly thresholds?: unknown;
+  };
 }
 
 /**
@@ -136,4 +165,33 @@ export interface ExploreRunnerResult {
     readonly output_tokens: number;
     readonly usd_cost: number;
   };
+  /**
+   * Phase 53 (DISC-01) — present ONLY when `ExploreRunnerOptions.incremental`
+   * was supplied. Carries the classifier verdict + the community batch plan so
+   * the explore stage can scope each mapper to its community and skip re-mapping
+   * unchanged batches. Absent (undefined) on the backward-compatible default
+   * path — existing consumers that never set `incremental` never see this key.
+   */
+  readonly batching?: {
+    /** SKIP | PARTIAL_UPDATE | ARCHITECTURE_UPDATE | FULL_UPDATE (post `--full`). */
+    readonly action: string;
+    /** Batching method actually used. */
+    readonly method: 'louvain' | 'count-fallback';
+    /** Modularity of the Louvain partition (null on the count-fallback). */
+    readonly modularity: number | null;
+    /** Every community batch (opaque ids + members). */
+    readonly batches: ReadonlyArray<{
+      readonly id: string;
+      readonly members: readonly string[];
+      readonly mergeable: boolean;
+      readonly kind: string;
+      readonly source: string;
+    }>;
+    /** The batch ids elected for re-map this cycle (SKIP ⇒ empty). */
+    readonly batchesToMap: readonly string[];
+    /** Per-batch neighborMap sidecar, keyed by batch id (selected batches only). */
+    readonly neighborMaps: Readonly<Record<string, unknown>>;
+    /** The change classifier's full result (structuralCount, pct, hints, reason, …). */
+    readonly classification: Readonly<Record<string, unknown>>;
+  };
 }

package/scripts/lib/manifest/skills.json

@@ -93,6 +93,14 @@
       "user_invocable": true,
       "tools": "Read, Write, Bash, Glob, Grep, AskUserQuestion, ToolSearch"
     },
+    {
+      "name": "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,
+      "registered_in_phase": "52"
+    },
     {
       "name": "continue",
       "description": "Alias for {{command_prefix}}resume - restore session context from the most recent checkpoint.",
@@ -127,7 +135,7 @@
       "name": "discover",
       "frontmatter_name": "discover",
       "description": "Stage 1.5 of 4 orchestrator that probes Figma / Refero / Pinterest connections, spawns design-context-builder (auto-detect + interview) and (via lazy gate) design-context-checker (6-dimension validator), producing .design/DESIGN-CONTEXT.md. Use after {{command_prefix}}scan when a fast-path context build is wanted instead of the full {{command_prefix}}explore. Activates for requests involving detecting an existing design system, inventorying tokens and components, or onboarding a brownfield repo.",
-      "argument_hint": "[--auto]",
+      "argument_hint": "[--auto] [--incremental] [--full]",
       "user_invocable": true
     },
     {
@@ -145,7 +153,7 @@
     {
       "name": "explore",
       "description": "Stage 2 of 5 - unified exploration merging inventory grep + design interview. Probes 6 connections, scans the codebase, conducts the AskUserQuestion interview, and writes .design/DESIGN.md + DESIGN-DEBT.md + DESIGN-CONTEXT.md. Use after {{command_prefix}}brief to map the existing system and lock decisions before planning. Activates for requests involving researching design direction, gathering references, or exploring visual options.",
-      "argument_hint": "[--skip-interview] [--skip-scan]",
+      "argument_hint": "[--skip-interview] [--skip-scan] [--incremental] [--full]",
       "tools": "Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__probe_connections, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__checkpoint, mcp__gdd_state__add_decision",
       "next_skills": [
         "plan"
@@ -244,6 +252,14 @@
       "user_invocable": true,
       "tools": "Read, Write, Bash, Grep, Glob"
     },
+    {
+      "name": "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,
+      "registered_in_phase": "52"
+    },
     {
       "name": "new-cycle",
       "description": "Start a new design cycle. Creates cycle scope in STATE.md, initializes .design/CYCLES.md entry. Each cycle has its own goal and tracks its own decisions/tasks/pipeline runs.",