@hegemonart/get-design-done 1.52.0 → 1.54.0

package/sdk/cli/index.js

@@ -527,6 +527,1405 @@ var require_concurrency_tuner = __commonJS({
   }
 });
 
+// scripts/lib/mappers/incremental-discover.cjs
+var require_incremental_discover = __commonJS({
+  "scripts/lib/mappers/incremental-discover.cjs"(exports2, module2) {
+    "use strict";
+    var path = require("node:path");
+    var fs = require("node:fs");
+    var { pathToFileURL } = require("node:url");
+    function pkgRoot() {
+      let dir = __dirname;
+      for (let i = 0; i < 10; i += 1) {
+        if (fs.existsSync(path.join(dir, "package.json"))) return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+      }
+      return process.cwd();
+    }
+    var ROOT = pkgRoot();
+    var MAPPERS_DIR = path.join(ROOT, "scripts", "lib", "mappers");
+    var SDK_FP_DIR = path.join(ROOT, "sdk", "fingerprint");
+    var _classify = null;
+    function classify(...args) {
+      if (!_classify) _classify = require(path.join(SDK_FP_DIR, "classify.cjs")).classify;
+      return _classify(...args);
+    }
+    var _batchMod = null;
+    var _neighborMod = null;
+    var _fpMod = null;
+    async function loadBatchMod() {
+      if (!_batchMod) {
+        _batchMod = await import(pathToFileURL(path.join(MAPPERS_DIR, "compute-batches.mjs")).href);
+      }
+      return _batchMod;
+    }
+    async function loadNeighborMod() {
+      if (!_neighborMod) {
+        _neighborMod = await import(pathToFileURL(path.join(MAPPERS_DIR, "neighbor-map.mjs")).href);
+      }
+      return _neighborMod;
+    }
+    async function loadFingerprintMod() {
+      if (!_fpMod) {
+        _fpMod = await import(pathToFileURL(path.join(SDK_FP_DIR, "index.ts")).href);
+      }
+      return _fpMod;
+    }
+    function nodeList(graph) {
+      return Array.isArray(graph && graph.nodes) ? graph.nodes : [];
+    }
+    function edgeList(graph) {
+      return Array.isArray(graph && graph.edges) ? graph.edges : [];
+    }
+    var STRUCTURAL_EDGE_TYPES = /* @__PURE__ */ new Set([
+      "composes",
+      "extends",
+      "depends-on",
+      "consumes-context",
+      "provides-context"
+    ]);
+    var FINGERPRINTABLE = /* @__PURE__ */ new Map([
+      ["component", "component"],
+      ["token", "token"],
+      ["motion-fragment", "motion"]
+    ]);
+    function indexForProjection(graph) {
+      const byId = /* @__PURE__ */ new Map();
+      for (const n of nodeList(graph)) {
+        if (n && typeof n.id === "string") byId.set(n.id, n);
+      }
+      const tokensOf = /* @__PURE__ */ new Map();
+      const variantsOf = /* @__PURE__ */ new Map();
+      const ensure = (map, id) => {
+        let s = map.get(id);
+        if (!s) {
+          s = /* @__PURE__ */ new Set();
+          map.set(id, s);
+        }
+        return s;
+      };
+      const typeOf = (id) => byId.get(id) && byId.get(id).type;
+      const nameOf = (id) => {
+        const node = byId.get(id);
+        return node && typeof node.name === "string" ? node.name : id;
+      };
+      for (const e of edgeList(graph)) {
+        if (!e || typeof e.source !== "string" || typeof e.target !== "string") continue;
+        const sType = typeOf(e.source);
+        const tType = typeOf(e.target);
+        if (e.type === "uses-token") {
+          if (sType === "component" && tType === "token") ensure(tokensOf, e.source).add(e.target);
+          else if (tType === "component" && sType === "token") ensure(tokensOf, e.target).add(e.source);
+        } else if (e.type === "extends") {
+          if (tType === "component" && (sType === "variant" || sType === "state")) {
+            ensure(variantsOf, e.target).add(nameOf(e.source));
+          } else if (sType === "component" && (tType === "variant" || tType === "state")) {
+            ensure(variantsOf, e.source).add(nameOf(e.target));
+          }
+        } else if (STRUCTURAL_EDGE_TYPES.has(e.type)) {
+          if (sType === "component" && tType === "state") ensure(variantsOf, e.source).add(nameOf(e.target));
+          else if (tType === "component" && sType === "state") ensure(variantsOf, e.target).add(nameOf(e.source));
+        }
+      }
+      return { byId, tokensOf, variantsOf };
+    }
+    function strArray(v) {
+      if (!Array.isArray(v)) return [];
+      const out = [];
+      const seen = /* @__PURE__ */ new Set();
+      for (const x of v) {
+        const s = typeof x === "string" ? x : x && typeof x.name === "string" ? x.name : null;
+        if (s != null && !seen.has(s)) {
+          seen.add(s);
+          out.push(s);
+        }
+      }
+      out.sort();
+      return out;
+    }
+    function propShape(props) {
+      if (!Array.isArray(props)) return [];
+      const out = [];
+      for (const p of props) {
+        if (typeof p === "string") {
+          out.push({ name: p, type: "" });
+        } else if (p && typeof p === "object" && typeof p.name === "string") {
+          out.push({
+            name: p.name,
+            type: typeof p.type === "string" ? p.type : "",
+            ...typeof p.optional === "boolean" ? { optional: p.optional } : {}
+          });
+        }
+      }
+      return out;
+    }
+    function projectNode(node, fpType, idx) {
+      if (fpType === "component") {
+        const usedTokens = idx.tokensOf.has(node.id) ? [...idx.tokensOf.get(node.id)].sort() : [];
+        const variantsFromGraph = idx.variantsOf.has(node.id) ? [...idx.variantsOf.get(node.id)] : [];
+        const variantsFromNode = strArray(node.exported_variants || node.variants);
+        const exportedVariants = [.../* @__PURE__ */ new Set([...variantsFromGraph, ...variantsFromNode])].sort();
+        return {
+          component_signature: {
+            name: typeof node.name === "string" ? node.name : node.id,
+            members: strArray(node.members)
+          },
+          props_shape: propShape(node.props),
+          used_tokens: usedTokens,
+          exported_variants: exportedVariants
+        };
+      }
+      if (fpType === "token") {
+        return {
+          token_name: typeof node.name === "string" ? node.name : node.id,
+          token_value: node.value === void 0 ? null : typeof node.value === "object" ? JSON.stringify(node.value) : node.value,
+          token_type: typeof node.subtype === "string" ? node.subtype : typeof node.token_type === "string" ? node.token_type : "",
+          ...typeof node.subtype === "string" ? { subtype: node.subtype } : {},
+          ...typeof node.theme_scope === "string" ? { theme_scope: node.theme_scope } : {}
+        };
+      }
+      return {
+        animation_target: typeof node.name === "string" ? node.name : node.id,
+        ...Number.isFinite(node.duration_ms) ? { duration_ms: node.duration_ms } : {},
+        ...typeof node.easing === "string" ? { easing: node.easing } : {}
+      };
+    }
+    function idNamespace(id) {
+      if (typeof id !== "string") return "unknown";
+      const i = id.indexOf(":");
+      return i > 0 ? id.slice(0, i) : id;
+    }
+    function isFileNode(node) {
+      return !!node && FINGERPRINTABLE.has(node.type);
+    }
+    function deriveDirShape(graph) {
+      const counts = {};
+      const layerHist = {};
+      let totalFiles = 0;
+      for (const n of nodeList(graph)) {
+        if (!isFileNode(n)) continue;
+        totalFiles += 1;
+        const ns = idNamespace(n.id);
+        let dir = ns;
+        if (n.type === "token" && typeof n.subtype === "string" && n.subtype.length) {
+          dir = `token:${n.subtype}`;
+        }
+        counts[dir] = (counts[dir] || 0) + 1;
+        layerHist[ns] = (layerHist[ns] || 0) + 1;
+      }
+      const dirs = Object.keys(counts).sort();
+      return { dirs, counts, layerHist, totalFiles };
+    }
+    function derivePrevDirShape(prevFingerprints) {
+      const fps = prevFingerprints && typeof prevFingerprints === "object" ? prevFingerprints : {};
+      const ids = Object.keys(fps);
+      if (ids.length === 0) return null;
+      const counts = {};
+      const layerHist = {};
+      for (const id of ids) {
+        const ns = idNamespace(id);
+        let dir = ns;
+        if (ns === "token") {
+          const parts = id.split(":");
+          if (parts.length >= 3 && parts[1]) dir = `token:${parts[1]}`;
+        }
+        counts[dir] = (counts[dir] || 0) + 1;
+        layerHist[ns] = (layerHist[ns] || 0) + 1;
+      }
+      return { dirs: Object.keys(counts).sort(), counts, layerHist };
+    }
+    function asFingerprint(v) {
+      if (v == null) return null;
+      if (typeof v === "string") return { full: v, structural: v };
+      if (typeof v === "object" && typeof v.full === "string") {
+        return { full: v.full, structural: typeof v.structural === "string" ? v.structural : v.full };
+      }
+      return null;
+    }
+    function buildCompareResults(graph, prevFingerprints, fingerprint, compareFingerprints) {
+      const idx = indexForProjection(graph);
+      const prev = prevFingerprints && typeof prevFingerprints === "object" ? prevFingerprints : {};
+      const fingerprints = {};
+      const compareResults = [];
+      const currentIds = /* @__PURE__ */ new Set();
+      for (const node of nodeList(graph)) {
+        if (!node || typeof node.id !== "string") continue;
+        const fpType = FINGERPRINTABLE.get(node.type);
+        if (!fpType) continue;
+        currentIds.add(node.id);
+        let fp;
+        try {
+          fp = fingerprint(projectNode(node, fpType, idx), fpType);
+        } catch {
+          compareResults.push({ id: node.id, type: node.type, change: "STRUCTURAL" });
+          continue;
+        }
+        fingerprints[node.id] = { full: fp.full, structural: fp.structural, type: node.type };
+        const before = asFingerprint(prev[node.id]);
+        const change = compareFingerprints(before, { full: fp.full, structural: fp.structural });
+        compareResults.push({ id: node.id, type: node.type, change });
+      }
+      for (const id of Object.keys(prev)) {
+        if (currentIds.has(id)) continue;
+        const before = asFingerprint(prev[id]);
+        const change = compareFingerprints(before, null);
+        const t = prev[id] && typeof prev[id] === "object" && typeof prev[id].type === "string" ? prev[id].type : idNamespace(id);
+        compareResults.push({ id, type: t, change });
+      }
+      return { fingerprints, compareResults };
+    }
+    function selectBatches(batches, action, affectedBatchHints) {
+      const all = Array.isArray(batches) ? batches : [];
+      if (action === "SKIP") return [];
+      if (action === "FULL_UPDATE") return all.slice();
+      const hints = new Set(Array.isArray(affectedBatchHints) ? affectedBatchHints : []);
+      if (hints.size === 0) return [];
+      const out = [];
+      for (const b of all) {
+        const members = Array.isArray(b && b.members) ? b.members : [];
+        if (members.some((m) => hints.has(m))) out.push(b);
+      }
+      return out;
+    }
+    async function planIncremental2(args) {
+      const { graph, prevFingerprints, opts } = args && typeof args === "object" ? args : {};
+      const o = opts && typeof opts === "object" ? opts : {};
+      const prev = prevFingerprints && typeof prevFingerprints === "object" ? prevFingerprints : {};
+      const { computeBatches } = await loadBatchMod();
+      const { batches, modularity, method } = computeBatches(graph, o.computeBatchesOpts);
+      const { fingerprint, compareFingerprints } = await loadFingerprintMod();
+      const { fingerprints, compareResults } = buildCompareResults(
+        graph,
+        prev,
+        fingerprint,
+        compareFingerprints
+      );
+      const currDirShape = deriveDirShape(graph);
+      let prevDirShape = derivePrevDirShape(prev);
+      if (o.hadPriorBaseline === false) prevDirShape = null;
+      const projectStats = {
+        totalFiles: currDirShape.totalFiles,
+        prevDirShape,
+        currDirShape: { dirs: currDirShape.dirs, counts: currDirShape.counts, layerHist: currDirShape.layerHist },
+        ...o.thresholds && typeof o.thresholds === "object" ? { thresholds: o.thresholds } : {}
+      };
+      const classification = classify(compareResults, projectStats);
+      const effectiveAction = o.forceFull ? "FULL_UPDATE" : classification.action;
+      const batchesToMap = selectBatches(batches, effectiveAction, classification.affectedBatchHints);
+      const neighborMaps = {};
+      if (batchesToMap.length > 0) {
+        const { buildNeighborMap } = await loadNeighborMod();
+        const cap = Number.isInteger(o.neighborCap) && o.neighborCap >= 0 ? o.neighborCap : 50;
+        for (const b of batchesToMap) {
+          if (b && typeof b.id === "string") {
+            neighborMaps[b.id] = buildNeighborMap(b, graph, { cap });
+          }
+        }
+      }
+      return {
+        action: effectiveAction,
+        batches,
+        batchesToMap,
+        neighborMaps,
+        fingerprints,
+        compareResults,
+        classification,
+        method,
+        modularity
+      };
+    }
+    module2.exports = {
+      planIncremental: planIncremental2,
+      // exported for the wiring layer + tests (pure helpers, no side effects).
+      selectBatches,
+      deriveDirShape,
+      derivePrevDirShape,
+      buildCompareResults,
+      projectNode,
+      indexForProjection,
+      FINGERPRINTABLE
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-01.cjs
+var require_ban_01 = __commonJS({
+  "scripts/lib/detect/rules/ban-01.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "border-left:\\s*[2-9][0-9]*px|border-right:\\s*[2-9][0-9]*px";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-01",
+      category: "decoration",
+      name: "Side-Stripe Borders",
+      description: "A thick (>=2px) left/right accent border \u2014 a dated, decorative side-stripe.",
+      references: ["reference/anti-patterns.md#BAN-01"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-02.cjs
+var require_ban_02 = __commonJS({
+  "scripts/lib/detect/rules/ban-02.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "background-clip:\\s*text|text-fill-color:\\s*transparent";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-02",
+      category: "decoration",
+      name: "Gradient Text",
+      description: "Gradient-filled text via background-clip:text \u2014 low legibility, an AI-era cliche.",
+      references: ["reference/anti-patterns.md#BAN-02"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-03.cjs
+var require_ban_03 = __commonJS({
+  "scripts/lib/detect/rules/ban-03.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "cubic-bezier\\(.*-[0-9]|bounce|elastic|spring\\(";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-03",
+      category: "motion",
+      name: "Bounce/Elastic Easing",
+      description: "Bounce/elastic/spring easing \u2014 playful overshoot that reads as unserious for product UI.",
+      references: ["reference/anti-patterns.md#BAN-03"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-05.cjs
+var require_ban_05 = __commonJS({
+  "scripts/lib/detect/rules/ban-05.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "background.*#000000|background.*rgb\\(0,\\s*0,\\s*0\\)";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-05",
+      category: "color",
+      name: "Pure Black Dark Mode",
+      description: "Pure #000 dark-mode background \u2014 harsh contrast + halation; use a near-black surface.",
+      references: ["reference/anti-patterns.md#BAN-05"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-06.cjs
+var require_ban_06 = __commonJS({
+  "scripts/lib/detect/rules/ban-06.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "user-scalable=no|maximum-scale=1";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-06",
+      category: "accessibility",
+      name: "Disabling Zoom",
+      description: "Viewport meta that disables pinch-zoom \u2014 a WCAG 1.4.4 failure.",
+      references: ["reference/anti-patterns.md#BAN-06"],
+      severity: "error",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-07.cjs
+var require_ban_07 = __commonJS({
+  "scripts/lib/detect/rules/ban-07.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = ":focus\\s*\\{[^}]*outline:\\s*(none|0)";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-07",
+      category: "accessibility",
+      name: "Naked outline: none",
+      description: "Removing the focus outline without a replacement \u2014 a keyboard-a11y failure.",
+      references: ["reference/anti-patterns.md#BAN-07"],
+      severity: "error",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-08.cjs
+var require_ban_08 = __commonJS({
+  "scripts/lib/detect/rules/ban-08.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "transition:\\s*all\\s";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-08",
+      category: "motion",
+      name: "transition: all",
+      description: "transition: all animates layout-triggering properties \u2014 jank; name the exact properties.",
+      references: ["reference/anti-patterns.md#BAN-08"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-09.cjs
+var require_ban_09 = __commonJS({
+  "scripts/lib/detect/rules/ban-09.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "transform:\\s*scale\\(\\s*0\\s*\\)|scale\\(\\s*0\\s*\\)";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-09",
+      category: "motion",
+      name: "scale(0) Animation Entry",
+      description: "Entering from scale(0) \u2014 nothing materializes from nothing; start at scale(0.95)+opacity.",
+      references: ["reference/anti-patterns.md#BAN-09"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-11.cjs
+var require_ban_11 = __commonJS({
+  "scripts/lib/detect/rules/ban-11.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "outline-(slate|zinc|neutral|gray|stone|blue|red|green|yellow|purple)-\\d+|img\\s*\\{[^}]*outline:\\s*[^}]*#[0-9a-fA-F]{3,8}";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-11",
+      category: "decoration",
+      name: "Tinted Image Outline",
+      description: "A colored outline on an image \u2014 color contamination; use low-opacity black/white.",
+      references: ["reference/anti-patterns.md#BAN-11"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-12.cjs
+var require_ban_12 = __commonJS({
+  "scripts/lib/detect/rules/ban-12.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "transition:\\s*all|transition-property:\\s*all";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-12",
+      category: "motion",
+      name: "transition: all (property)",
+      description: "transition: all / transition-property: all \u2014 recalculates layout every transition.",
+      references: ["reference/anti-patterns.md#BAN-12"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-13.cjs
+var require_ban_13 = __commonJS({
+  "scripts/lib/detect/rules/ban-13.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "will-change:\\s*all";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-13",
+      category: "performance",
+      name: "will-change: all",
+      description: "will-change: all promotes every property to its own GPU layer \u2014 huge texture memory.",
+      references: ["reference/anti-patterns.md#BAN-13"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/index.cjs
+var require_rules = __commonJS({
+  "scripts/lib/detect/rules/index.cjs"(exports2, module2) {
+    "use strict";
+    var r0 = require_ban_01();
+    var r1 = require_ban_02();
+    var r2 = require_ban_03();
+    var r3 = require_ban_05();
+    var r4 = require_ban_06();
+    var r5 = require_ban_07();
+    var r6 = require_ban_08();
+    var r7 = require_ban_09();
+    var r8 = require_ban_11();
+    var r9 = require_ban_12();
+    var r10 = require_ban_13();
+    var RULES = [r0, r1, r2, r3, r4, r5, r6, r7, r8, r9, r10];
+    var EXEMPT = Object.freeze(["BAN-04", "BAN-10"]);
+    module2.exports = { RULES, EXEMPT };
+  }
+});
+
+// scripts/lib/detect/engine.cjs
+var require_engine = __commonJS({
+  "scripts/lib/detect/engine.cjs"(exports2, module2) {
+    "use strict";
+    var fs = require("node:fs");
+    var path = require("node:path");
+    var { RULES, EXEMPT } = require_rules();
+    var SCANNABLE_EXT = /* @__PURE__ */ new Set([".html", ".htm", ".css", ".scss", ".jsx", ".tsx", ".js", ".ts", ".vue", ".svelte"]);
+    var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", ".next", "coverage", ".design", ".planning"]);
+    function walk(root) {
+      const out = [];
+      if (!fs.existsSync(root)) return out;
+      const st = fs.statSync(root);
+      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 selectRules(ruleId) {
+      if (!ruleId) return RULES;
+      const id = String(ruleId).toUpperCase();
+      return RULES.filter((r) => r.id === id);
+    }
+    function scanContent(content, ctx, rules) {
+      const findings = [];
+      for (const rule of rules) {
+        let hits = [];
+        try {
+          hits = rule.matcher({ content, ext: ctx.ext, path: ctx.path }) || [];
+        } catch {
+          hits = [];
+        }
+        for (const h of hits) {
+          findings.push({
+            ruleId: rule.id,
+            category: rule.category,
+            name: rule.name,
+            severity: rule.severity,
+            file: ctx.path,
+            line: h.line,
+            column: h.column,
+            match: h.match,
+            references: rule.references
+          });
+        }
+      }
+      return findings;
+    }
+    function run6(root, opts) {
+      const o = opts || {};
+      const rules = selectRules(o.ruleId);
+      const cwd = o.cwd || process.cwd();
+      const files = walk(root);
+      const findings = [];
+      let errors = 0;
+      for (const abs of files) {
+        let content;
+        try {
+          content = fs.readFileSync(abs, "utf8");
+        } catch {
+          errors++;
+          continue;
+        }
+        const rel = path.relative(cwd, abs).split(path.sep).join("/");
+        findings.push(...scanContent(content, { path: rel || abs, ext: path.extname(abs).toLowerCase() }, rules));
+      }
+      findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column || a.ruleId.localeCompare(b.ruleId));
+      return { findings, filesScanned: files.length, errors, rules: rules.length };
+    }
+    module2.exports = { run: run6, walk, scanContent, selectRules, RULES, EXEMPT, SCANNABLE_EXT, SKIP_DIRS };
+  }
+});
+
+// scripts/lib/detect/stack.cjs
+var require_stack = __commonJS({
+  "scripts/lib/detect/stack.cjs"(exports2, module2) {
+    "use strict";
+    var fs = require("node:fs");
+    var path = require("node:path");
+    var { walk, SKIP_DIRS } = require_engine();
+    function readDeps(root) {
+      const pkgPath = path.basename(String(root || "")) === "package.json" ? root : path.join(root || ".", "package.json");
+      let raw;
+      try {
+        raw = fs.readFileSync(pkgPath, "utf8");
+      } catch {
+        return { deps: {}, present: false, error: null };
+      }
+      let pkg;
+      try {
+        pkg = JSON.parse(raw);
+      } catch (e) {
+        return { deps: {}, present: true, error: "package.json is not valid JSON" + (e && e.message ? `: ${e.message}` : "") };
+      }
+      if (!pkg || typeof pkg !== "object") {
+        return { deps: {}, present: true, error: "package.json did not parse to an object" };
+      }
+      const deps = {};
+      for (const field of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+        const m = pkg[field];
+        if (m && typeof m === "object" && !Array.isArray(m)) {
+          for (const k of Object.keys(m)) deps[k] = m[k];
+        }
+      }
+      return { deps, present: true, error: null };
+    }
+    function hasDep(deps, name) {
+      return Object.prototype.hasOwnProperty.call(deps, name);
+    }
+    function hasDepPrefix(deps, prefix) {
+      for (const k of Object.keys(deps)) {
+        if (k === prefix || k.startsWith(prefix)) return true;
+      }
+      return false;
+    }
+    function hasTopLevelFile(root, names) {
+      let entries;
+      try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+      } catch {
+        return false;
+      }
+      const set = new Set(entries.filter((e) => e.isFile()).map((e) => e.name));
+      for (const n of names) if (set.has(n)) return true;
+      return false;
+    }
+    function hasTopLevelConfig(root, stem) {
+      let entries;
+      try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+      } catch {
+        return false;
+      }
+      const prefix = stem + ".";
+      for (const e of entries) {
+        if (e.isFile() && e.name.startsWith(prefix)) return true;
+      }
+      return false;
+    }
+    function hasTopLevelDir(root, name) {
+      try {
+        const st = fs.statSync(path.join(root, name));
+        return st.isDirectory();
+      } catch {
+        return false;
+      }
+    }
+    function findFileMatching(root, re) {
+      let files;
+      try {
+        files = walk(root);
+      } catch {
+        return null;
+      }
+      for (const abs of files) {
+        if (re.test(path.basename(abs))) return relish(root, abs);
+      }
+      return null;
+    }
+    function findContentMatching(root, re, fileFilter) {
+      let files;
+      try {
+        files = walk(root);
+      } catch {
+        return null;
+      }
+      for (const abs of files) {
+        if (fileFilter && !fileFilter(abs)) continue;
+        let text;
+        try {
+          text = fs.readFileSync(abs, "utf8");
+        } catch {
+          continue;
+        }
+        const m = re.exec(text);
+        if (m) return { file: relish(root, abs), match: m[0] };
+      }
+      return null;
+    }
+    function relish(root, abs) {
+      const rel = path.relative(root, abs);
+      return (rel || abs).split(path.sep).join("/");
+    }
+    var DS_PROBES = [
+      {
+        id: "shadcn",
+        // shadcn is a tailwind super-set: detect it FIRST so a shadcn project (which also
+        // ships tailwind) is labeled shadcn rather than the more generic tailwind.
+        detect(root, deps) {
+          const hasComponentsJson = hasTopLevelFile(root, ["components.json"]);
+          const cnHit = hasComponentsJson ? null : findContentMatching(root, /\bcn\s*\(/, (abs) => /utils\.(t|j)sx?$/.test(abs.split(path.sep).join("/")));
+          if (hasComponentsJson) return { ev: "components.json present (shadcn/ui)" };
+          if (cnHit) return { ev: `cn() helper in ${cnHit.file} (shadcn/ui)` };
+          return null;
+        }
+      },
+      {
+        id: "tailwind",
+        detect(root, deps) {
+          if (hasDep(deps, "tailwindcss")) return { ev: "tailwindcss in dependencies" };
+          if (hasTopLevelConfig(root, "tailwind.config")) return { ev: "tailwind.config.* present" };
+          const themeHit = findContentMatching(root, /@theme\b/, (abs) => /\.css$/.test(abs));
+          if (themeHit) return { ev: `@theme directive in ${themeHit.file} (tailwind v4)` };
+          return null;
+        }
+      },
+      {
+        id: "radix-themes",
+        detect(root, deps) {
+          if (hasDep(deps, "@radix-ui/themes")) return { ev: "@radix-ui/themes in dependencies" };
+          return null;
+        }
+      },
+      {
+        id: "mui",
+        detect(root, deps) {
+          if (hasDep(deps, "@mui/material")) return { ev: "@mui/material in dependencies" };
+          return null;
+        }
+      },
+      {
+        id: "chakra",
+        detect(root, deps) {
+          if (hasDep(deps, "@chakra-ui/react")) return { ev: "@chakra-ui/react in dependencies" };
+          return null;
+        }
+      },
+      {
+        id: "vanilla-extract",
+        detect(root, deps) {
+          if (hasDep(deps, "@vanilla-extract/css")) return { ev: "@vanilla-extract/css in dependencies" };
+          const cssTs = findFileMatching(root, /\.css\.ts$/);
+          if (cssTs) return { ev: `*.css.ts file ${cssTs} (vanilla-extract)` };
+          return null;
+        }
+      },
+      {
+        id: "styled-components",
+        detect(root, deps) {
+          if (hasDep(deps, "styled-components")) return { ev: "styled-components in dependencies" };
+          return null;
+        }
+      },
+      {
+        id: "css-modules",
+        // Weakest signal (a plain file pattern, no dep). Last so any explicit DS wins over it.
+        detect(root, deps) {
+          const mod = findFileMatching(root, /\.module\.css$/);
+          if (mod) return { ev: `*.module.css file ${mod} (CSS Modules)` };
+          return null;
+        }
+      }
+    ];
+    function detectDs(root, deps) {
+      for (const probe of DS_PROBES) {
+        let res = null;
+        try {
+          res = probe.detect(root, deps);
+        } catch {
+          res = null;
+        }
+        if (res) return { ds: probe.id, evidence: res.ev };
+      }
+      return { ds: null, evidence: "no design-system signal (no known DS dep, config file, or file pattern)" };
+    }
+    function detectFramework(root, deps) {
+      if (hasDep(deps, "next")) {
+        const router = hasTopLevelDir(root, "app") ? "app-router" : hasTopLevelDir(root, "pages") ? "pages-router" : hasTopLevelDir(root, "src") && hasTopLevelDir(path.join(root, "src"), "app") ? "app-router (src/)" : "router undetermined";
+        return { framework: "nextjs", evidence: `next in dependencies (${router})` };
+      }
+      if (hasDepPrefix(deps, "@remix-run/")) {
+        return { framework: "remix", evidence: "@remix-run/* in dependencies" };
+      }
+      if (hasDep(deps, "astro") || hasTopLevelConfig(root, "astro.config")) {
+        return { framework: "astro", evidence: hasDep(deps, "astro") ? "astro in dependencies" : "astro.config.* present" };
+      }
+      if (hasDep(deps, "@sveltejs/kit") || hasTopLevelConfig(root, "svelte.config")) {
+        return {
+          framework: "sveltekit",
+          evidence: hasDep(deps, "@sveltejs/kit") ? "@sveltejs/kit in dependencies" : "svelte.config.* present"
+        };
+      }
+      if (hasDep(deps, "storybook") || hasDepPrefix(deps, "@storybook/")) {
+        return { framework: "storybook", evidence: "storybook / @storybook/* in dependencies" };
+      }
+      if ((hasDep(deps, "vite") || hasTopLevelConfig(root, "vite.config")) && (hasDep(deps, "react") || hasDep(deps, "react-dom"))) {
+        return { framework: "vite-react", evidence: "vite + react in dependencies (no next/remix/astro/sveltekit)" };
+      }
+      return { framework: null, evidence: "no framework signal (no next/remix/vite-react/astro/sveltekit/storybook)" };
+    }
+    var MOTION_PROBES = [
+      {
+        id: "framer-motion",
+        detect(deps) {
+          if (hasDep(deps, "framer-motion")) return "framer-motion in dependencies";
+          if (hasDep(deps, "motion")) return "motion in dependencies (framer-motion v11+)";
+          return null;
+        }
+      },
+      {
+        id: "gsap",
+        detect(deps) {
+          if (hasDep(deps, "gsap")) return "gsap in dependencies";
+          return null;
+        }
+      },
+      {
+        id: "motion-one",
+        detect(deps) {
+          if (hasDepPrefix(deps, "@motionone/")) return "@motionone/* in dependencies";
+          return null;
+        }
+      },
+      {
+        id: "react-spring",
+        detect(deps) {
+          if (hasDep(deps, "react-spring") || hasDepPrefix(deps, "@react-spring/")) return "react-spring / @react-spring/* in dependencies";
+          return null;
+        }
+      }
+    ];
+    function detectMotion(deps) {
+      const libs = [];
+      const evidence = [];
+      for (const probe of MOTION_PROBES) {
+        let ev = null;
+        try {
+          ev = probe.detect(deps);
+        } catch {
+          ev = null;
+        }
+        if (ev) {
+          libs.push(probe.id);
+          evidence.push(`${probe.id}: ${ev}`);
+        }
+      }
+      return { motion_libs: libs, evidence };
+    }
+    function detectStack2(root) {
+      const dir = root || process.cwd();
+      const evidence = {};
+      let exists = false;
+      try {
+        exists = fs.existsSync(dir);
+      } catch {
+        exists = false;
+      }
+      if (!exists) {
+        return {
+          ds: null,
+          framework: null,
+          motion_libs: [],
+          evidence: { note: `root path does not exist: ${dir}` }
+        };
+      }
+      const { deps, present, error } = readDeps(dir);
+      if (!present) evidence.note = "no package.json at root \u2014 relying on config-file + file-pattern probes only";
+      else if (error) evidence.note = `${error} \u2014 relying on config-file + file-pattern probes only`;
+      let ds = null;
+      let framework = null;
+      let motion_libs = [];
+      try {
+        const dsr = detectDs(dir, deps);
+        ds = dsr.ds;
+        evidence.ds = dsr.evidence;
+      } catch (e) {
+        evidence.ds = "ds detection error: " + (e && e.message ? e.message : String(e));
+      }
+      try {
+        const fwr = detectFramework(dir, deps);
+        framework = fwr.framework;
+        evidence.framework = fwr.evidence;
+      } catch (e) {
+        evidence.framework = "framework detection error: " + (e && e.message ? e.message : String(e));
+      }
+      try {
+        const mr = detectMotion(deps);
+        motion_libs = mr.motion_libs;
+        evidence.motion = mr.evidence;
+      } catch (e) {
+        evidence.motion = ["motion detection error: " + (e && e.message ? e.message : String(e))];
+      }
+      return { ds, framework, motion_libs, evidence };
+    }
+    var HELP = `gdd stack detection \u2014 fingerprint a project's design-system / framework / motion stack.
+
+Usage:
+  detect-stack [root] [options]
+
+Arguments:
+  [root]            Project directory to scan (defaults to the current directory).
+
+Options:
+  --json            Machine-readable JSON (default).
+  --pretty          Pretty-printed human summary.
+  -h, --help        This help.
+
+Always exits 0 \u2014 an undetected stack is reported, not an error.`;
+    function parseArgs2(argv) {
+      const opts = { root: null, json: true, pretty: false, help: false };
+      for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--json") opts.json = true;
+        else if (a === "--pretty") {
+          opts.pretty = true;
+          opts.json = false;
+        } else if (a === "-h" || a === "--help") opts.help = true;
+        else if (!a.startsWith("-") && opts.root === null) opts.root = a;
+      }
+      return opts;
+    }
+    function renderPretty(res) {
+      const lines = [];
+      lines.push("gdd stack:");
+      lines.push(`  design-system : ${res.ds || "(none detected)"}`);
+      lines.push(`  framework     : ${res.framework || "(none detected)"}`);
+      lines.push(`  motion        : ${res.motion_libs.length ? res.motion_libs.join(", ") : "(none detected)"}`);
+      if (res.evidence && res.evidence.note) lines.push(`  note          : ${res.evidence.note}`);
+      return lines.join("\n");
+    }
+    function main2(argv, io) {
+      const o = io || {};
+      const log = o.log || ((s) => process.stdout.write(s + "\n"));
+      const opts = parseArgs2(argv);
+      if (opts.help) {
+        log(HELP);
+        return 0;
+      }
+      const root = opts.root || o.cwd || process.cwd();
+      const res = detectStack2(root);
+      if (opts.pretty) log(renderPretty(res));
+      else log(JSON.stringify(res, null, 2));
+      return 0;
+    }
+    module2.exports = {
+      detectStack: detectStack2,
+      main: main2,
+      // internals exported for unit reuse / introspection (kept stable for executors B & F).
+      readDeps,
+      hasDep,
+      hasDepPrefix,
+      detectDs,
+      detectFramework,
+      detectMotion,
+      parseArgs: parseArgs2,
+      HELP,
+      SKIP_DIRS
+    };
+    if (require.main === module2) process.exit(main2(process.argv.slice(2)));
+  }
+});
+
+// scripts/lib/mapper-spawn.cjs
+var require_mapper_spawn = __commonJS({
+  "scripts/lib/mapper-spawn.cjs"(exports2, module2) {
+    "use strict";
+    var fs = require("node:fs");
+    var path = require("node:path");
+    var BLOCK_HEADER = "## Stack-specific guidance";
+    var ADDENDUM_SEPARATOR = "\n\n---\n\n";
+    var CATEGORY_ORDER = ["system", "framework", "motion"];
+    function normKey(value) {
+      return typeof value === "string" ? value.trim().toLowerCase() : "";
+    }
+    function baseNameNoExt(p) {
+      if (typeof p !== "string" || p.length === 0) return "";
+      const tail2 = p.replace(/\\/g, "/").split("/").pop() || "";
+      return tail2.replace(/\.md$/i, "");
+    }
+    function classifyEntry(entry) {
+      let category = null;
+      const explicitKind = normKey(entry.kind || entry.category);
+      if (explicitKind === "system" || explicitKind === "ds" || explicitKind === "design-system") {
+        category = "system";
+      } else if (explicitKind === "framework") {
+        category = "framework";
+      } else if (explicitKind === "motion") {
+        category = "motion";
+      } else if (typeof entry.path === "string") {
+        const p = entry.path.replace(/\\/g, "/");
+        if (/(^|\/)reference\/systems\//i.test(p) || /(^|\/)systems\//i.test(p)) category = "system";
+        else if (/(^|\/)reference\/frameworks\//i.test(p) || /(^|\/)frameworks\//i.test(p)) category = "framework";
+        else if (/(^|\/)reference\/motion\//i.test(p) || /(^|\/)motion\//i.test(p)) category = "motion";
+      }
+      let key = normKey(entry.stack);
+      if (key === "") key = normKey(baseNameNoExt(entry.path));
+      if (key === "") {
+        const nameParts = normKey(entry.name).split("-").filter(Boolean);
+        key = nameParts.length > 0 ? nameParts[nameParts.length - 1] : "";
+      }
+      return { category, key };
+    }
+    function composesInto(entry, mapperName) {
+      if (!entry || entry.type !== "stack-addendum") return false;
+      const list = entry.composes_into;
+      if (!Array.isArray(list)) return false;
+      return list.some((m) => normKey(m) === normKey(mapperName));
+    }
+    function readAddendumBody(entry, refDir) {
+      if (typeof entry.path !== "string" || entry.path.length === 0) return null;
+      const rel = entry.path.replace(/\\/g, "/");
+      const candidates = [];
+      if (path.isAbsolute(rel)) {
+        candidates.push(rel);
+      } else {
+        candidates.push(path.resolve(refDir, rel));
+        const stripped = rel.replace(/^reference\//i, "");
+        if (stripped !== rel) candidates.push(path.resolve(refDir, stripped));
+      }
+      for (const abs of candidates) {
+        let body;
+        try {
+          body = fs.readFileSync(abs, "utf8");
+        } catch {
+          continue;
+        }
+        const trimmed = body.replace(/\s+$/, "").replace(/^/, "");
+        if (trimmed.trim().length > 0) return trimmed;
+      }
+      return null;
+    }
+    function composeAddendums(mapperName, stack, opts) {
+      const used = [];
+      const missing = [];
+      const empty = () => ({ block: "", used, missing });
+      const o = opts || {};
+      const cap = Number.isInteger(o.cap) && o.cap >= 0 ? o.cap : 3;
+      const refDir = typeof o.refDir === "string" && o.refDir.length > 0 ? o.refDir : process.cwd();
+      if (!stack || typeof stack !== "object" || cap === 0) return empty();
+      const registry = o.registry;
+      const entries = registry && Array.isArray(registry.entries) ? registry.entries : [];
+      const detected = {
+        system: normKey(stack.ds),
+        framework: normKey(stack.framework),
+        // motion is a list; take the first non-empty entry (cap allows only one
+        // motion addendum, so the leading detected lib wins).
+        motion: Array.isArray(stack.motion_libs) ? normKey(stack.motion_libs.find((m) => normKey(m) !== "")) : ""
+      };
+      const candidates = [];
+      for (const entry of entries) {
+        if (!composesInto(entry, mapperName)) continue;
+        const { category, key } = classifyEntry(entry);
+        if (category === null || key === "") continue;
+        candidates.push({ entry, category, key });
+      }
+      const bodies = [];
+      for (const category of CATEGORY_ORDER) {
+        if (used.length >= cap) break;
+        const want = detected[category];
+        if (want === "") continue;
+        const hit = candidates.find((c) => c.category === category && c.key === want);
+        if (!hit) {
+          missing.push(want);
+          continue;
+        }
+        const body = readAddendumBody(hit.entry, refDir);
+        if (body === null) {
+          missing.push(want);
+          continue;
+        }
+        bodies.push(body);
+        used.push(typeof hit.entry.name === "string" && hit.entry.name.length > 0 ? hit.entry.name : hit.key);
+      }
+      if (bodies.length === 0) return empty();
+      const block = `${BLOCK_HEADER}
+
+${bodies.join(ADDENDUM_SEPARATOR)}`;
+      return { block, used, missing };
+    }
+    function applyAddendums2(spec, stack, opts) {
+      if (!spec || typeof spec !== "object") {
+        return { spec, block: "", used: [], missing: [] };
+      }
+      const mapperName = typeof spec.name === "string" ? spec.name : "";
+      const { block, used, missing } = composeAddendums(mapperName, stack, opts);
+      if (block !== "") {
+        const base = typeof spec.prompt === "string" ? spec.prompt : "";
+        spec.prompt = base === "" ? block : `${base}
+
+${block}`;
+      }
+      return { spec, block, used, missing };
+    }
+    module2.exports = {
+      composeAddendums,
+      applyAddendums: applyAddendums2,
+      // Exported for unit-level coverage + reuse by the runner wiring (executor F).
+      classifyEntry,
+      composesInto,
+      BLOCK_HEADER
+    };
+  }
+});
+
+// scripts/lib/reference-registry.cjs
+var require_reference_registry = __commonJS({
+  "scripts/lib/reference-registry.cjs"(exports2, module2) {
+    "use strict";
+    var fs = require("fs");
+    var path = require("path");
+    var REPO_ROOT2 = path.resolve(__dirname, "..", "..");
+    var DEFAULT_REGISTRY_PATH = path.join(REPO_ROOT2, "reference", "registry.json");
+    var _cache = null;
+    var _cachePath = null;
+    function loadRegistry({ cwd } = {}) {
+      const p = cwd ? path.join(cwd, "reference", "registry.json") : DEFAULT_REGISTRY_PATH;
+      if (_cache && _cachePath === p) return _cache;
+      _cachePath = p;
+      _cache = JSON.parse(fs.readFileSync(p, "utf8"));
+      return _cache;
+    }
+    function list({ type, cwd } = {}) {
+      const reg = loadRegistry({ cwd });
+      if (!type) return reg.entries.slice();
+      return reg.entries.filter((e) => e.type === type);
+    }
+    function find(name, { cwd } = {}) {
+      const reg = loadRegistry({ cwd });
+      return reg.entries.find((e) => e.name === name) || null;
+    }
+    function validateRegistry({ cwd } = {}) {
+      const root = cwd || REPO_ROOT2;
+      const refDir = path.join(root, "reference");
+      const reg = (() => {
+        try {
+          return JSON.parse(fs.readFileSync(path.join(refDir, "registry.json"), "utf8"));
+        } catch {
+          return { entries: [] };
+        }
+      })();
+      const onDisk = /* @__PURE__ */ new Set();
+      for (const leaf of walk(refDir)) {
+        const rel = path.relative(root, leaf).replace(/\\/g, "/");
+        if (rel === "reference/registry.json") continue;
+        if (rel.endsWith(".schema.json")) continue;
+        if (rel.startsWith("reference/schemas/")) continue;
+        if (rel.startsWith("reference/data/")) continue;
+        if (!/\.(md|json)$/.test(rel)) continue;
+        onDisk.add(rel);
+      }
+      const registryPaths = new Set(reg.entries.map((e) => e.path));
+      const missingInRegistry = [...onDisk].filter((p) => !registryPaths.has(p)).sort();
+      const danglingInRegistry = reg.entries.filter((e) => !fs.existsSync(path.join(root, e.path))).map((e) => ({ name: e.name, path: e.path }));
+      const nameCount = {}, pathCount = {};
+      for (const e of reg.entries) {
+        nameCount[e.name] = (nameCount[e.name] || 0) + 1;
+        pathCount[e.path] = (pathCount[e.path] || 0) + 1;
+      }
+      const duplicates = [];
+      for (const [k, v] of Object.entries(nameCount)) if (v > 1) duplicates.push({ kind: "name", key: k, count: v });
+      for (const [k, v] of Object.entries(pathCount)) if (v > 1) duplicates.push({ kind: "path", key: k, count: v });
+      return {
+        ok: missingInRegistry.length === 0 && danglingInRegistry.length === 0 && duplicates.length === 0,
+        missingInRegistry,
+        danglingInRegistry,
+        duplicates
+      };
+    }
+    function* walk(dir) {
+      let entries;
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) yield* walk(full);
+        else if (e.isFile()) yield full;
+      }
+    }
+    module2.exports = { list, find, validateRegistry, loadRegistry };
+  }
+});
+
 // sdk/cli/index.ts
 var index_exports = {};
 __export(index_exports, {
@@ -5560,6 +6959,9 @@ var import_node_path14 = require("node:path");
 // scripts/lib/explore-parallel-runner/index.ts
 var import_node_path12 = require("node:path");
 var import_concurrency_tuner = __toESM(require_concurrency_tuner());
+var import_incremental_discover = __toESM(require_incremental_discover());
+var import_stack = __toESM(require_stack());
+var import_mapper_spawn = __toESM(require_mapper_spawn());
 
 // scripts/lib/explore-parallel-runner/mappers.ts
 var import_node_fs12 = require("node:fs");
@@ -5897,12 +7299,109 @@ var DEFAULT_MAPPERS = Object.freeze([
     prompt: "Describe z-order, focal points, and attention grammar. Output to .design/map/visual-hierarchy.md \u2014 one section per surface describing layering, emphasis, and scan path."
   })
 ]);
+function agentNameOf(spec) {
+  const base = spec.agentPath.replace(/\\/g, "/").split("/").pop()?.replace(/\.md$/i, "");
+  return base && base.length > 0 ? base : spec.name;
+}
+function composeMapperSpecs(specs, cwd, addendumOpts, logger) {
+  const missingByMapper = {};
+  const opt = addendumOpts ?? {};
+  if (opt.enabled === false) return { specs, missingByMapper };
+  try {
+    const root = typeof opt.root === "string" ? opt.root : cwd;
+    const detect = typeof opt.detectStack === "function" ? opt.detectStack : import_stack.detectStack;
+    const stack = detect(root);
+    let registry = opt.registry;
+    const refDir = typeof opt.refDir === "string" ? opt.refDir : (0, import_node_path12.resolve)(cwd, "reference");
+    if (registry === void 0) {
+      try {
+        const { loadRegistry } = require_reference_registry();
+        registry = loadRegistry({ cwd });
+      } catch {
+        registry = void 0;
+      }
+    }
+    let anyChanged = false;
+    const recomposed = specs.map((spec) => {
+      const agentName = agentNameOf(spec);
+      const carrier = { name: agentName, prompt: spec.prompt };
+      const { block, missing } = (0, import_mapper_spawn.applyAddendums)(carrier, stack, {
+        registry,
+        refDir
+      });
+      if (Array.isArray(missing) && missing.length > 0) {
+        missingByMapper[agentName] = missing;
+      }
+      if (block && block.length > 0 && carrier.prompt !== spec.prompt) {
+        anyChanged = true;
+        return Object.freeze({ ...spec, prompt: carrier.prompt });
+      }
+      return spec;
+    });
+    if (anyChanged) {
+      logger.info("explore.runner.addendums_composed", {
+        mappers_augmented: recomposed.filter((s, i) => s !== specs[i]).length,
+        ds: stack && stack.ds ? stack.ds : null,
+        framework: stack && stack.framework ? stack.framework : null,
+        motion_libs: stack && Array.isArray(stack.motion_libs) ? stack.motion_libs.length : 0
+      });
+      return { specs: Object.freeze(recomposed), missingByMapper };
+    }
+    return { specs, missingByMapper };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logger.warn("explore.runner.addendums_failed", { message });
+    return { specs, missingByMapper };
+  }
+}
 async function run3(opts) {
-  const specs = opts.mappers ?? DEFAULT_MAPPERS;
+  const baseSpecs = opts.mappers ?? DEFAULT_MAPPERS;
   const cwd = opts.cwd ?? process.cwd();
   const concurrency = opts.concurrency ?? (0, import_concurrency_tuner.resolveConcurrency)();
   const logger = getLogger().child("explore.runner");
+  const { specs } = composeMapperSpecs(baseSpecs, cwd, opts.addendums, logger);
   const outputPath = (0, import_node_path12.resolve)(cwd, ".design/DESIGN-PATTERNS.md");
+  let batching = void 0;
+  if (opts.incremental && opts.incremental.graph !== void 0 && opts.incremental.graph !== null) {
+    try {
+      const plan = await (0, import_incremental_discover.planIncremental)({
+        graph: opts.incremental.graph,
+        prevFingerprints: opts.incremental.prevFingerprints,
+        opts: {
+          ...opts.incremental.forceFull !== void 0 ? { forceFull: opts.incremental.forceFull } : {},
+          ...opts.incremental.computeBatchesOpts !== void 0 ? { computeBatchesOpts: opts.incremental.computeBatchesOpts } : {},
+          ...opts.incremental.neighborCap !== void 0 ? { neighborCap: opts.incremental.neighborCap } : {},
+          ...opts.incremental.thresholds !== void 0 ? { thresholds: opts.incremental.thresholds } : {}
+        }
+      });
+      batching = Object.freeze({
+        action: plan.action,
+        method: plan.method,
+        modularity: plan.modularity,
+        batches: Object.freeze(plan.batches.map((b) => 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) => 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) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.warn("explore.runner.batching_failed", { message });
+      batching = void 0;
+    }
+  }
   logger.info("explore.runner.started", {
     mapper_count: specs.length,
     concurrency
@@ -5924,7 +7423,8 @@ async function run3(opts) {
       }),
       parallel_count: 0,
       serial_count: 0,
-      total_usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 }
+      total_usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+      ...batching !== void 0 ? { batching } : {}
     });
   }
   const safeSpecs = [];
@@ -6040,7 +7540,8 @@ async function run3(opts) {
       input_tokens: totalInput,
       output_tokens: totalOutput,
       usd_cost: totalCost
-    }
+    },
+    ...batching !== void 0 ? { batching } : {}
   });
 }