@hegemonart/get-design-done 1.53.0 → 1.54.0

package/sdk/cli/index.js

@@ -850,6 +850,1082 @@ var require_incremental_discover = __commonJS({
   }
 });
 
+// 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, {
@@ -5884,6 +6960,8 @@ var import_node_path14 = require("node:path");
 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");
@@ -6221,11 +7299,67 @@ 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) {