@hegemonart/get-design-done 1.40.0 → 1.41.0

package/scripts/lib/detect/engine.cjs

@@ -0,0 +1,83 @@
+'use strict';
+// Phase 41 — gdd-detect engine. Pure, dep-free (regex-fast path). Walks a path, runs each rule's
+// matcher against file content, returns structured findings. The DOM-aware (jsdom) + URL (puppeteer)
+// paths are layered on in cli.cjs via soft try-require; the engine itself never touches the network
+// or any optional dependency — so the SC#10 network-isolation scan stays clean.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { RULES, EXEMPT } = require('./rules/index.cjs');
+
+const SCANNABLE_EXT = new Set(['.html', '.htm', '.css', '.scss', '.jsx', '.tsx', '.js', '.ts', '.vue', '.svelte']);
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.design', '.planning']);
+
+/** Recursively collect scannable file paths under `root` (a file or dir). */
+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;
+}
+
+/** Select the active rule set. `ruleId` (e.g. 'BAN-08') narrows to one rule. */
+function selectRules(ruleId) {
+  if (!ruleId) return RULES;
+  const id = String(ruleId).toUpperCase();
+  return RULES.filter((r) => r.id === id);
+}
+
+/** Run `rules` over one file's content. Returns findings with file-relative metadata merged in. */
+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;
+}
+
+/**
+ * Run the detector over a path.
+ * @param {string} root file or directory
+ * @param {{ruleId?: string, cwd?: string}} [opts]
+ * @returns {{findings: object[], filesScanned: number, errors: number, rules: number}}
+ */
+function run(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 };
+}
+
+module.exports = { run, walk, scanContent, selectRules, RULES, EXEMPT, SCANNABLE_EXT, SKIP_DIRS };

package/scripts/lib/detect/rule-schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://get-design-done.example/schemas/gdd-detect-rule.schema.json",
+  "title": "gdd-detect rule",
+  "description": "Phase 41 — the shape of a scripts/lib/detect/rules/ban-NN.cjs module export. Each rule ports a statically-detectable BAN-NN anti-pattern from reference/anti-patterns.md into an executable matcher. The markdown catalogue stays the canonical prose; the rule files are the canonical executable; scripts/sync-rule-catalogue.cjs keeps them in parity.",
+  "type": "object",
+  "required": ["id", "category", "name", "description", "references", "severity"],
+  "additionalProperties": true,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^BAN-[0-9]{2}$",
+      "description": "The BAN-NN id — matches a `### BAN-NN:` heading + a `bdId: BAN-NN` marker in reference/anti-patterns.md."
+    },
+    "category": {
+      "type": "string",
+      "enum": ["decoration", "motion", "color", "accessibility", "performance", "layout", "typography"],
+      "description": "Coarse grouping for report sectioning."
+    },
+    "name": { "type": "string", "minLength": 1, "description": "Human title (the BAN heading text after the id)." },
+    "description": { "type": "string", "minLength": 1, "description": "One-line explanation of what the rule flags + why." },
+    "references": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "pattern": "^reference/.+#" },
+      "description": "Bidirectional links to the catalogue paragraph(s) that explain the alternative (e.g. reference/anti-patterns.md#BAN-04)."
+    },
+    "severity": { "type": "string", "enum": ["error", "warn"], "description": "error fails a strict gate; warn is advisory (open-Q default: error|warn)." },
+    "pattern": { "type": "string", "description": "The regex source ported from the catalogue's **Grep** (regex-fast path)." }
+  }
+}

package/scripts/lib/detect/rules/ban-01.cjs

@@ -0,0 +1,33 @@
+'use strict';
+// Phase 41 — BAN-01: Side-Stripe Borders. Ported from reference/anti-patterns.md (its own **Grep**).
+// Pure, dep-free. No `require`. The matcher scans ctx.content; line/column are 1-based.
+
+const PATTERN = "border-left:\\s*[2-9][0-9]*px|border-right:\\s*[2-9][0-9]*px";
+
+/** @param {{content: string, ext: string, path: string}} ctx @returns {{line:number,column:number,match:string}[]} */
+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++; // zero-width guard
+  }
+  return out;
+}
+
+module.exports = {
+  id: "BAN-01",
+  category: "decoration",
+  name: "Side-Stripe Borders",
+  description: "A thick (>=2px) left/right accent border — a dated, decorative side-stripe.",
+  references: ["reference/anti-patterns.md#BAN-01"],
+  severity: "warn",
+  pattern: PATTERN,
+  matcher,
+};

package/scripts/lib/detect/rules/ban-02.cjs

@@ -0,0 +1,33 @@
+'use strict';
+// Phase 41 — BAN-02: Gradient Text. Ported from reference/anti-patterns.md (its own **Grep**).
+// Pure, dep-free. No `require`. The matcher scans ctx.content; line/column are 1-based.
+
+const PATTERN = "background-clip:\\s*text|text-fill-color:\\s*transparent";
+
+/** @param {{content: string, ext: string, path: string}} ctx @returns {{line:number,column:number,match:string}[]} */
+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++; // zero-width guard
+  }
+  return out;
+}
+
+module.exports = {
+  id: "BAN-02",
+  category: "decoration",
+  name: "Gradient Text",
+  description: "Gradient-filled text via background-clip:text — low legibility, an AI-era cliche.",
+  references: ["reference/anti-patterns.md#BAN-02"],
+  severity: "warn",
+  pattern: PATTERN,
+  matcher,
+};

package/scripts/lib/detect/rules/ban-03.cjs

@@ -0,0 +1,33 @@
+'use strict';
+// Phase 41 — BAN-03: Bounce/Elastic Easing. Ported from reference/anti-patterns.md (its own **Grep**).
+// Pure, dep-free. No `require`. The matcher scans ctx.content; line/column are 1-based.
+
+const PATTERN = "cubic-bezier\\(.*-[0-9]|bounce|elastic|spring\\(";
+
+/** @param {{content: string, ext: string, path: string}} ctx @returns {{line:number,column:number,match:string}[]} */
+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++; // zero-width guard
+  }
+  return out;
+}
+
+module.exports = {
+  id: "BAN-03",
+  category: "motion",
+  name: "Bounce/Elastic Easing",
+  description: "Bounce/elastic/spring easing — playful overshoot that reads as unserious for product UI.",
+  references: ["reference/anti-patterns.md#BAN-03"],
+  severity: "warn",
+  pattern: PATTERN,
+  matcher,
+};

package/scripts/lib/detect/rules/ban-05.cjs

@@ -0,0 +1,33 @@
+'use strict';
+// Phase 41 — BAN-05: Pure Black Dark Mode. Ported from reference/anti-patterns.md (its own **Grep**).
+// Pure, dep-free. No `require`. The matcher scans ctx.content; line/column are 1-based.
+
+const PATTERN = "background.*#000000|background.*rgb\\(0,\\s*0,\\s*0\\)";
+
+/** @param {{content: string, ext: string, path: string}} ctx @returns {{line:number,column:number,match:string}[]} */
+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++; // zero-width guard
+  }
+  return out;
+}
+
+module.exports = {
+  id: "BAN-05",
+  category: "color",
+  name: "Pure Black Dark Mode",
+  description: "Pure #000 dark-mode background — harsh contrast + halation; use a near-black surface.",
+  references: ["reference/anti-patterns.md#BAN-05"],
+  severity: "warn",
+  pattern: PATTERN,
+  matcher,
+};

package/scripts/lib/detect/rules/ban-06.cjs

@@ -0,0 +1,33 @@
+'use strict';
+// Phase 41 — BAN-06: Disabling Zoom. Ported from reference/anti-patterns.md (its own **Grep**).
+// Pure, dep-free. No `require`. The matcher scans ctx.content; line/column are 1-based.
+
+const PATTERN = "user-scalable=no|maximum-scale=1";
+
+/** @param {{content: string, ext: string, path: string}} ctx @returns {{line:number,column:number,match:string}[]} */
+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++; // zero-width guard
+  }
+  return out;
+}
+
+module.exports = {
+  id: "BAN-06",
+  category: "accessibility",
+  name: "Disabling Zoom",
+  description: "Viewport meta that disables pinch-zoom — a WCAG 1.4.4 failure.",
+  references: ["reference/anti-patterns.md#BAN-06"],
+  severity: "error",
+  pattern: PATTERN,
+  matcher,
+};

package/scripts/lib/detect/rules/ban-07.cjs

@@ -0,0 +1,33 @@
+'use strict';
+// Phase 41 — BAN-07: Naked outline: none. Ported from reference/anti-patterns.md (its own **Grep**).
+// Pure, dep-free. No `require`. The matcher scans ctx.content; line/column are 1-based.
+
+const PATTERN = ":focus\\s*\\{[^}]*outline:\\s*(none|0)";
+
+/** @param {{content: string, ext: string, path: string}} ctx @returns {{line:number,column:number,match:string}[]} */
+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++; // zero-width guard
+  }
+  return out;
+}
+
+module.exports = {
+  id: "BAN-07",
+  category: "accessibility",
+  name: "Naked outline: none",
+  description: "Removing the focus outline without a replacement — a keyboard-a11y failure.",
+  references: ["reference/anti-patterns.md#BAN-07"],
+  severity: "error",
+  pattern: PATTERN,
+  matcher,
+};

package/scripts/lib/detect/rules/ban-08.cjs

@@ -0,0 +1,33 @@
+'use strict';
+// Phase 41 — BAN-08: transition: all. Ported from reference/anti-patterns.md (its own **Grep**).
+// Pure, dep-free. No `require`. The matcher scans ctx.content; line/column are 1-based.
+
+const PATTERN = "transition:\\s*all\\s";
+
+/** @param {{content: string, ext: string, path: string}} ctx @returns {{line:number,column:number,match:string}[]} */
+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++; // zero-width guard
+  }
+  return out;
+}
+
+module.exports = {
+  id: "BAN-08",
+  category: "motion",
+  name: "transition: all",
+  description: "transition: all animates layout-triggering properties — jank; name the exact properties.",
+  references: ["reference/anti-patterns.md#BAN-08"],
+  severity: "warn",
+  pattern: PATTERN,
+  matcher,
+};

package/scripts/lib/detect/rules/ban-09.cjs

@@ -0,0 +1,33 @@
+'use strict';
+// Phase 41 — BAN-09: scale(0) Animation Entry. Ported from reference/anti-patterns.md (its own **Grep**).
+// Pure, dep-free. No `require`. The matcher scans ctx.content; line/column are 1-based.
+
+const PATTERN = "transform:\\s*scale\\(\\s*0\\s*\\)|scale\\(\\s*0\\s*\\)";
+
+/** @param {{content: string, ext: string, path: string}} ctx @returns {{line:number,column:number,match:string}[]} */
+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++; // zero-width guard
+  }
+  return out;
+}
+
+module.exports = {
+  id: "BAN-09",
+  category: "motion",
+  name: "scale(0) Animation Entry",
+  description: "Entering from scale(0) — nothing materializes from nothing; start at scale(0.95)+opacity.",
+  references: ["reference/anti-patterns.md#BAN-09"],
+  severity: "warn",
+  pattern: PATTERN,
+  matcher,
+};

package/scripts/lib/detect/rules/ban-11.cjs

@@ -0,0 +1,33 @@
+'use strict';
+// Phase 41 — BAN-11: Tinted Image Outline. Ported from reference/anti-patterns.md (its own **Grep**).
+// Pure, dep-free. No `require`. The matcher scans ctx.content; line/column are 1-based.
+
+const PATTERN = "outline-(slate|zinc|neutral|gray|stone|blue|red|green|yellow|purple)-\\d+|img\\s*\\{[^}]*outline:\\s*[^}]*#[0-9a-fA-F]{3,8}";
+
+/** @param {{content: string, ext: string, path: string}} ctx @returns {{line:number,column:number,match:string}[]} */
+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++; // zero-width guard
+  }
+  return out;
+}
+
+module.exports = {
+  id: "BAN-11",
+  category: "decoration",
+  name: "Tinted Image Outline",
+  description: "A colored outline on an image — color contamination; use low-opacity black/white.",
+  references: ["reference/anti-patterns.md#BAN-11"],
+  severity: "warn",
+  pattern: PATTERN,
+  matcher,
+};

package/scripts/lib/detect/rules/ban-12.cjs

@@ -0,0 +1,33 @@
+'use strict';
+// Phase 41 — BAN-12: transition: all (property). Ported from reference/anti-patterns.md (its own **Grep**).
+// Pure, dep-free. No `require`. The matcher scans ctx.content; line/column are 1-based.
+
+const PATTERN = "transition:\\s*all|transition-property:\\s*all";
+
+/** @param {{content: string, ext: string, path: string}} ctx @returns {{line:number,column:number,match:string}[]} */
+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++; // zero-width guard
+  }
+  return out;
+}
+
+module.exports = {
+  id: "BAN-12",
+  category: "motion",
+  name: "transition: all (property)",
+  description: "transition: all / transition-property: all — recalculates layout every transition.",
+  references: ["reference/anti-patterns.md#BAN-12"],
+  severity: "warn",
+  pattern: PATTERN,
+  matcher,
+};

package/scripts/lib/detect/rules/ban-13.cjs

@@ -0,0 +1,33 @@
+'use strict';
+// Phase 41 — BAN-13: will-change: all. Ported from reference/anti-patterns.md (its own **Grep**).
+// Pure, dep-free. No `require`. The matcher scans ctx.content; line/column are 1-based.
+
+const PATTERN = "will-change:\\s*all";
+
+/** @param {{content: string, ext: string, path: string}} ctx @returns {{line:number,column:number,match:string}[]} */
+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++; // zero-width guard
+  }
+  return out;
+}
+
+module.exports = {
+  id: "BAN-13",
+  category: "performance",
+  name: "will-change: all",
+  description: "will-change: all promotes every property to its own GPU layer — huge texture memory.",
+  references: ["reference/anti-patterns.md#BAN-13"],
+  severity: "warn",
+  pattern: PATTERN,
+  matcher,
+};

package/scripts/lib/detect/rules/index.cjs

@@ -0,0 +1,21 @@
+'use strict';
+// Phase 41 — rule registry. Loads every scripts/lib/detect/rules/ban-NN.cjs and exposes the
+// matcher-exempt set (subjective BAN rules with no static matcher: BAN-04 behavior, BAN-10 DOM-depth).
+
+const r0 = require('./ban-01.cjs');
+const r1 = require('./ban-02.cjs');
+const r2 = require('./ban-03.cjs');
+const r3 = require('./ban-05.cjs');
+const r4 = require('./ban-06.cjs');
+const r5 = require('./ban-07.cjs');
+const r6 = require('./ban-08.cjs');
+const r7 = require('./ban-09.cjs');
+const r8 = require('./ban-11.cjs');
+const r9 = require('./ban-12.cjs');
+const r10 = require('./ban-13.cjs');
+
+const RULES = [r0, r1, r2, r3, r4, r5, r6, r7, r8, r9, r10];
+// Subjective BAN rules documented in reference/anti-patterns.md but NOT statically detectable.
+const EXEMPT = Object.freeze(['BAN-04', 'BAN-10']);
+
+module.exports = { RULES, EXEMPT };

package/scripts/lib/i18n/index.cjs

@@ -0,0 +1,95 @@
+'use strict';
+// Phase 40.5 — i18n/index.cjs — GDD CLI localization resolver.
+//
+// Resolves a locale (config override > env LANG > English), a fallback chain (locale → base → en),
+// and translates a message key against per-locale flat-JSON tables. The pure functions (baseLocale,
+// fallbackChain, resolveLocale, translate, descriptionFor) take their data as arguments and touch
+// neither fs nor env directly — so they are trivially unit-testable. `loadTable` is the only fs reader.
+//
+// Contract: reference/cli-localization.md. Fallback is always to `en` (the complete source table).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const KNOWN_LOCALES = Object.freeze(['en', 'ru', 'uk', 'de', 'fr', 'zh', 'ja']);
+const DEFAULT_LOCALE = 'en';
+const MESSAGES_DIR = path.join(__dirname, 'messages');
+
+/** Normalize a raw locale token: lowercase, `_`→`-`, strip an encoding suffix (`ru_RU.UTF-8` → `ru-ru`). */
+function normalizeLocale(code) {
+  if (!code) return '';
+  return String(code).split('.')[0].split(':')[0].trim().toLowerCase().replace(/_/g, '-');
+}
+
+/** The base of a locale (`de-de` → `de`; `en` → `en`). */
+function baseLocale(code) {
+  return normalizeLocale(code).split('-')[0];
+}
+
+/** Resolution chain: [normalized, base, 'en'] with duplicates removed. */
+function fallbackChain(code) {
+  const norm = normalizeLocale(code);
+  const chain = [];
+  for (const c of [norm, baseLocale(norm), DEFAULT_LOCALE]) {
+    if (c && !chain.includes(c)) chain.push(c);
+  }
+  return chain.length ? chain : [DEFAULT_LOCALE];
+}
+
+/**
+ * Resolve the active locale. Precedence: explicit config.locale > env.LANG/LC_ALL > 'en'.
+ * @param {{env?: object, configLocale?: string}} [opts]
+ */
+function resolveLocale(opts) {
+  const o = opts || {};
+  const fromConfig = normalizeLocale(o.configLocale);
+  if (fromConfig) return fromConfig;
+  const env = o.env || {};
+  const fromEnv = normalizeLocale(env.LC_ALL || env.LC_MESSAGES || env.LANG || env.LANGUAGE);
+  if (fromEnv && fromEnv !== 'c' && fromEnv !== 'posix') return fromEnv;
+  return DEFAULT_LOCALE;
+}
+
+/**
+ * Translate `key` for `locale` against the supplied `tables` map ({ <locale>: {<key>: <string>} }).
+ * Walks the fallback chain; returns the first hit, else the key itself (so a missing key is visible,
+ * never throws).
+ */
+function translate(tables, key, locale) {
+  const map = tables || {};
+  for (const loc of fallbackChain(locale)) {
+    const t = map[loc];
+    if (t && Object.prototype.hasOwnProperty.call(t, key) && typeof t[key] === 'string') return t[key];
+  }
+  return key;
+}
+
+/**
+ * Resolve a skill/agent description for `locale`: frontmatter.description_i18n[<chain>] || .description.
+ * Opt-in + backward-compatible — absent description_i18n falls straight back to the English description.
+ */
+function descriptionFor(frontmatter, locale) {
+  const fm = frontmatter || {};
+  const i18n = fm.description_i18n;
+  if (i18n && typeof i18n === 'object') {
+    for (const loc of fallbackChain(locale)) {
+      if (typeof i18n[loc] === 'string' && i18n[loc].trim()) return i18n[loc];
+    }
+  }
+  return fm.description || '';
+}
+
+/** Read a locale's flat-JSON table from disk. Returns {} on missing/parse error (fail-safe → fallback). */
+function loadTable(locale, dir) {
+  const file = path.join(dir || MESSAGES_DIR, `${normalizeLocale(locale) || DEFAULT_LOCALE}.json`);
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+module.exports = {
+  KNOWN_LOCALES, DEFAULT_LOCALE, MESSAGES_DIR,
+  normalizeLocale, baseLocale, fallbackChain, resolveLocale, translate, descriptionFor, loadTable,
+};

package/scripts/lib/i18n/messages/de.json

@@ -0,0 +1,7 @@
+{
+  "_meta": { "locale": "de", "coverage": "placeholder", "fallback": "en" },
+  "help.tagline": "Eine Design-Qualitäts-Pipeline für KI-Coding-Agenten.",
+  "status.complete": "Fertig.",
+  "status.in_progress": "In Bearbeitung.",
+  "status.blocked": "Blockiert."
+}

package/scripts/lib/i18n/messages/en.json

@@ -0,0 +1,27 @@
+{
+  "_meta": { "locale": "en", "coverage": "complete", "fallback": null },
+  "help.usage": "Usage: gdd <command> [options]",
+  "help.tagline": "A design-quality pipeline for AI coding agents.",
+  "help.commands_header": "Commands",
+  "help.options_header": "Options",
+  "help.more": "Run `gdd help <command>` for details on a command.",
+  "help.pipeline": "Pipeline: brief -> explore -> plan -> design -> verify",
+  "error.no_state": "No .design/STATE.md found. Run /gdd:start to initialize a cycle.",
+  "error.no_config": "No .design/config.json found; using defaults.",
+  "error.stage_locked": "This stage is locked under the current cycle mode.",
+  "error.permission_denied": "Permission denied: your role cannot perform this action on this section.",
+  "error.budget_cap": "Budget cap reached. Raise the cap in .design/budget.json or wait for the next task.",
+  "error.connection_unavailable": "Connection unavailable. Configure it via /gdd:connections.",
+  "error.invalid_locale": "Unknown locale. Known locales: en, ru, uk, de, fr, zh, ja.",
+  "error.merge_conflict": "STATE.md has a merge conflict. Run the conflict-resolver to reconcile per section.",
+  "error.decision_locked": "This decision is locked. Use /gdd:unlock-decision <id> --approver <who> to reopen it.",
+  "error.no_telemetry": "No cost telemetry yet. Run a cycle first.",
+  "prompt.brief_header": "Stage 1 of 5 - Brief: capture the problem, audience, constraints, and metrics.",
+  "prompt.explore_header": "Stage 2 of 5 - Explore: inventory the design surface and interview for intent.",
+  "prompt.plan_header": "Stage 3 of 5 - Plan: decompose the work into tasks.",
+  "prompt.design_header": "Stage 4 of 5 - Design: execute the plan.",
+  "prompt.verify_header": "Stage 5 of 5 - Verify: score and audit against the design system.",
+  "status.complete": "Complete.",
+  "status.in_progress": "In progress.",
+  "status.blocked": "Blocked."
+}

package/scripts/lib/i18n/messages/fr.json

@@ -0,0 +1,7 @@
+{
+  "_meta": { "locale": "fr", "coverage": "placeholder", "fallback": "en" },
+  "help.tagline": "Un pipeline de qualité de conception pour les agents de codage IA.",
+  "status.complete": "Terminé.",
+  "status.in_progress": "En cours.",
+  "status.blocked": "Bloqué."
+}

package/scripts/lib/i18n/messages/ja.json

@@ -0,0 +1,7 @@
+{
+  "_meta": { "locale": "ja", "coverage": "placeholder", "fallback": "en" },
+  "help.tagline": "AI コーディングエージェントのためのデザイン品質パイプライン。",
+  "status.complete": "完了。",
+  "status.in_progress": "進行中。",
+  "status.blocked": "ブロック中。"
+}