@hegemonart/get-design-done 1.40.0 → 1.41.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.40.0"
+    "version": "1.41.0"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.40.0",
+      "version": "1.41.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,84 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.41.0] - 2026-06-02
+
+### Phase 41 — Deterministic Anti-Pattern CLI (`gdd-detect`)
+
+GDD's BAN-NN anti-pattern catalogue was consumable only by spawning a Claude session through
+`design-auditor` — no fast CI gate, no pre-commit hook, no zero-LLM regression check. 41 ships
+**`gdd-detect`**: a **dep-free, offline** Node CLI that scans HTML/CSS/JSX for the 11 statically-
+detectable BAN rules and emits JSON or human findings, each linked to its catalogue paragraph.
+(Inspired by `pbakaus/impeccable`.) **No new runtime dependency, no new egress.**
+
+### Breaking changes
+
+**None.** `gdd-detect` is purely additive — a new `bin` entry + a new `lint:design` script + new
+`scripts/lib/detect/` modules. Nothing existing changes behavior; `design-auditor` swaps its inline
+BAN greps for a `gdd-detect --json` call (same findings, deterministic). Upgrading from v1.40.5 is a no-op for existing workflows.
+
+### Added
+
+- **`bin/gdd-detect`** (`gdd-detect <path> [--json] [--fast] [--rule BAN-NN] [--puppeteer]`) — exit
+  `0` clean / `2` findings / `1` invocation error. Recursive scan of HTML/CSS/JSX/TSX.
+- **`scripts/lib/detect/`** — a pure, dep-free engine + `rule-schema.json` + 11 per-rule matchers
+  (`rules/ban-NN.cjs`) ported verbatim from the catalogue's own `**Grep**` patterns
+  (BAN-01/02/03/05/06/07/08/09/11/12/13). BAN-04 + BAN-10 are subjective (matcher-exempt).
+- **`scripts/sync-rule-catalogue.cjs`** — bidirectional parity gate: every rule ↔ a `### BAN-NN:`
+  heading + a `bdId: BAN-NN` marker; no orphans; no un-ported detectable rule.
+- **`scripts/hooks/pre-commit-detect.sh`** — opt-in pre-commit scaffold.
+- **`lint:design`** npm script + `sync:rule-catalogue` npm script.
+
+### Changed
+
+- **`reference/anti-patterns.md`** — `bdId: BAN-NN` markers under every BAN heading.
+- **`agents/design-auditor.md`** — Pillar-7 inline BAN greps replaced by one `gdd-detect --json` call.
+- **`skills/quality-gate/SKILL.md`** — `lint:design` added to the Phase-25 auto-detect linter allowlist.
+
+### Notes
+
+- **Two execution paths**: regex-fast (the dep-free default) and DOM-aware (`jsdom`, a soft
+  `try-require` optional — **not** a `package.json` dependency); `--fast` forces regex; absent jsdom
+  falls back with a one-line warning. A `http(s)://` path needs `--puppeteer` (also soft-optional) and
+  prints a clear install message otherwise — never a stack trace. The CLI is **offline by default** (a
+  static network-isolation test fails the build on any network primitive in the detect tree).
+- 6-manifest lockstep at **v1.41.0** + `OFF_CADENCE_VERSIONS.add('1.41.0')` (minor) + the 35 live-pinned
+  `manifests-version.txt` baselines forward-propagated 1.40.5 → 1.41.0.
+- Inventory: tarball golden 731 → 747 (+16: `bin/gdd-detect` + `scripts/lib/detect/**`). No
+  skill/agent/registry deltas (`sync-rule-catalogue.cjs` + the pre-commit scaffold are maintainer-only).
+
+---
+
+## [1.40.5] - 2026-06-01
+
+### Phase 40.5 — GDD CLI Localization
+
+GDD's README is multilingual, but the CLI talked English. 40.5 adds locale resolution + per-locale
+message tables for the highest-traffic surface — `--help`, common error messages, and skill prompt
+headers. English is always the final fallback, so a partial locale never breaks the CLI. **No new
+runtime dependency, no new egress.**
+
+### Added
+
+- **`scripts/lib/i18n/index.cjs`** — locale resolver: `resolveLocale` (`config.locale` > env `LANG`/`LC_ALL` > `en`), `fallbackChain` (`locale → base → en`), `translate` (chain walk; a missing key returns the key, never throws), `descriptionFor` (`description_i18n` || English). Pure functions + a thin `loadTable` reader.
+- **`scripts/lib/i18n/messages/{en,ru,uk,de,fr,zh,ja}.json`** — flat message tables. `en` is the complete source (24 keys: `help.*`/`error.*`/`prompt.*`/`status.*`), `ru` a full translation, `uk`/`de`/`fr`/`zh`/`ja` placeholders (a `_meta` marker + a starter subset) that fall back to English.
+- **`skills/locale/SKILL.md`** (`/gdd:locale [<code>]`) — inspect the resolved locale + per-locale coverage, or set `.design/config.json#locale`.
+- **`reference/cli-localization.md`** — the resolver contract + the add-a-locale contribution path (translate the table, add a `NOTICE` translator credit, open a PR; warn-only completeness). Registered. Distinct from `reference/i18n.md` (which covers *user-design* i18n).
+
+### Changed
+
+- **`reference/schemas/config.schema.json`** — + `locale` (enum en/ru/uk/de/fr/zh/ja); `generated.d.ts` regenerated.
+- **`agents/README.md`** — document the opt-in `description_i18n` frontmatter field (falls back to the English `description`; backward-compatible — the 28.5 contract validates it only when present).
+
+### Notes
+
+- **No new runtime dependency, no new egress.** Pure resolver + JSON tables + docs.
+- The completeness gate is **warn-only** — only `en` + `ru` are full; the five placeholder locales rely on the English fallback and are never required to be 100%.
+- 6-manifest lockstep at **v1.40.5** + `OFF_CADENCE_VERSIONS.add('1.40.5')` + the 34 live-pinned `manifests-version.txt` baselines forward-propagated 1.40.0 → 1.40.5.
+- Inventory relock: registry-diff 159 → 160 (+`cli-localization`), skill-list 82 → 83 (+`locale`), skill-length-distribution relocked, tarball golden 721 → 731 (+10). No agent/event deltas. Root `SKILL.md` command table += `locale`.
+
+---
+
 ## [1.40.0] - 2026-06-01
 
 ### Phase 40 — Team Collaboration Mode

package/README.md

@@ -194,6 +194,14 @@ GDD migrates *your* design systems (above) — now it migrates **itself**. When
 
 GDD's single-operator baseline now extends to **teams** — git-native + advisory, no server. Two developers working a cycle on parallel branches merge their `.design/STATE.md` **per section** ([`section-merge`](scripts/lib/collab/section-merge.cjs) unions decisions by `D-id`; a real conflict is only a same-id divergence, which [`conflict-resolver`](agents/conflict-resolver.md) reconciles with human confirmation — never auto-picking or dropping a decision). Decisions carry optional `[author= co-author=]` attribution, move through an async review queue (`proposed → reviewing → approved → locked`) with **hard locks** (the only escape is an audited [`/gdd:unlock-decision`](skills/unlock-decision/SKILL.md)), and [`/gdd:review-decisions`](skills/review-decisions/SKILL.md) surfaces what's pending. [`decision-journal-exporter`](agents/decision-journal-exporter.md) publishes a **pseudonymized, read-only** Notion/Confluence journal for stakeholders who don't run GDD. `gdd_cycle_mode` (designer/dev/full) partitions a cycle by role, a `permissions` model gates per-section writes, and `collab.multi_writer_enabled` switches the advisory lock to a team-mode backoff. The full contract: [`reference/multi-author-model.md`](reference/multi-author-model.md). **Everything is off by default** — a single-operator project is unaffected. **No new runtime dependency.**
 
+### CLI localization (v1.40.5)
+
+GDD's README is multilingual — now its **CLI** is too. [`/gdd:locale <code>`](skills/locale/SKILL.md) sets the language of `--help`, common error messages, and skill prompt headers, resolved by [`scripts/lib/i18n`](scripts/lib/i18n/index.cjs) (precedence: `config.locale` > env `LANG` > `en`; fallback chain `locale → base → en`). Flat-JSON message tables ship for **en** (complete source), **ru** (full), and **uk/de/fr/zh/ja** placeholders — a missing key always falls back to English, so a partial locale never breaks the CLI. Skills + agents can carry an opt-in `description_i18n` map. Adding a locale is a PR: translate the table, add a `NOTICE` credit (the contribution path is in [`reference/cli-localization.md`](reference/cli-localization.md)). Completeness is **warn-only**. **No new runtime dependency.**
+
+### Deterministic anti-pattern CLI — `gdd-detect` (v1.41.0)
+
+GDD's BAN-NN anti-pattern catalogue is now executable. [`gdd-detect`](bin/gdd-detect) is a **dep-free, offline** Node CLI that scans HTML/CSS/JSX for the 11 statically-detectable BAN rules ([`scripts/lib/detect/rules/`](scripts/lib/detect/)) — `transition: all`, `will-change: all`, gradient text, bounce easing, `scale(0)` entry, naked `outline: none`, pure-black dark mode, disabled zoom, tinted image outline — each finding linked to its [`reference/anti-patterns.md`](reference/anti-patterns.md) paragraph. `gdd-detect <path> [--json] [--fast] [--rule BAN-NN]` exits `0` clean / `2` findings / `1` error. The rule files are the canonical executable; the markdown stays canonical prose; [`sync-rule-catalogue`](scripts/sync-rule-catalogue.cjs) keeps them in parity. `npm run lint:design` is the CI gate; an opt-in pre-commit scaffold ships too. `design-auditor` and the Phase-25 quality-gate consume it; `jsdom`/`puppeteer` are soft-optional (regex-fast is the default). **No new runtime dependency.**
+
 ### Previous releases
 
 - **v1.26.0** — Headless Model Resolver (per-runtime tier→model map, `resolved_models` router field, per-runtime price tables, `reasoning-class` runtime-neutral alias).

package/SKILL.md

@@ -107,6 +107,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `migrate [--yes] [--dry-run]` | `get-design-done:gdd-migrate` | Phase 39.5 — migrate a project off GDD's own deprecated paths after an upgrade; reads `reference/DEPRECATIONS.md` via `deprecation-registry.cjs`, previews a diff, applies on confirm. Preview-first; never edits silently |
 | `review-decisions [<id>] [--pending]` | `get-design-done:gdd-review-decisions` | Phase 40 — surface the async decision-review queue (`proposed → reviewing → approved → locked`); `--pending` shows decisions still awaiting action. Read-only |
 | `unlock-decision <id> --approver <who> [--reason <text>] [--dry-run]` | `get-design-done:gdd-unlock-decision` | Phase 40 — reopen a LOCKED decision (the only escape hatch); requires an approver + writes an audit entry; previews before writing |
+| `locale [<code>]` | `get-design-done:gdd-locale` | Phase 40.5 — inspect or set the GDD CLI locale (en/ru/uk/de/fr/zh/ja) for `--help`, errors, and skill prompt headers; missing keys fall back to English. No arg reports the resolved locale + coverage |
 
 ## Handoff Routing
 

package/agents/README.md

@@ -39,6 +39,7 @@ Every agent file begins with a YAML frontmatter block. All fields except `model`
 |-------|------|-----------------|---------|
 | `name` | kebab-case string | unique within plugin | Identifier passed to the `Task` tool — must match the filename without `.md` |
 | `description` | string | free-form | One sentence: what the agent does + when it is spawned |
+| `description_i18n` | object | `{ <locale>: "<description>" }` | **Phase 40.5, opt-in.** Localized descriptions keyed by locale (en/ru/uk/de/fr/zh/ja). `scripts/lib/i18n/index.cjs` `descriptionFor(frontmatter, locale)` resolves it via the fallback chain and falls back to the English `description` when a locale is absent. Backward-compatible — omit it and nothing changes. |
 | `tools` | comma-separated list | `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`, `Task`, `WebFetch`, `TodoWrite`, `mcp__*` | Claude tools the agent may use — list only what is needed |
 | `color` | enum | `yellow`, `green`, `blue`, `red` | Terminal display color for the agent's output |
 | `model` | enum (optional) | `inherit`, `sonnet`, `haiku` | Omit to use the project's configured profile default. Use `inherit` to bypass the profile and use the highest available model (quality-tier work) |

package/agents/design-auditor.md

@@ -277,12 +277,11 @@ grep -rEn "confirm\b|Confirm\b|areYouSure|destructive|danger" src/ --include="*.
 Collect findings from the micro-polish sections of the mapper outputs (`.design/map/motion.md`, `.design/map/tokens.md`, `.design/map/visual-hierarchy.md`, `.design/map/a11y.md`). If those files are not yet available, run targeted grep passes:
 
 ```bash
-# transition:all violations
-grep -rEn "transition:\s*all|transition-property:\s*all" src/ --include="*.css" --include="*.scss" 2>/dev/null | head -10
-grep -rEn 'className="[^"]*\btransition\b[^-]' src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10
-
-# will-change:all violations
-grep -rEn "will-change:\s*all" src/ --include="*.css" --include="*.scss" 2>/dev/null | head -5
+# BAN-NN anti-patterns — Phase 41: run the deterministic detector instead of hand-grepping each
+# rule. One pass, --json, every BAN rule (transition:all, will-change:all, gradient text, bounce
+# easing, scale(0), naked outline:none, pure-black dark mode, disabled zoom, tinted image outline),
+# each finding linked to its reference/anti-patterns.md paragraph. Offline + zero-LLM.
+node "${CLAUDE_PLUGIN_ROOT:-.}/bin/gdd-detect" src/ --json 2>/dev/null || true
 
 # Missing AnimatePresence initial={false}
 grep -rEn "<AnimatePresence" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | grep -v "initial={false}" | head -10

package/bin/gdd-detect

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// bin/gdd-detect — Phase 41 deterministic anti-pattern CLI.
+//
+// Thin CJS entry: the engine + CLI are plain dep-free CommonJS under scripts/lib/detect/, so unlike
+// bin/gdd-sdk this needs no compiled/strip-types dual mode — it just requires the CLI and forwards
+// argv + the exit code (0 clean · 2 findings · 1 invocation error).
+
+'use strict';
+
+const path = require('node:path');
+
+let cli;
+try {
+  cli = require(path.resolve(__dirname, '..', 'scripts', 'lib', 'detect', 'cli.cjs'));
+} catch (err) {
+  process.stderr.write('gdd-detect: failed to load the detector: ' + (err && err.message ? err.message : String(err)) + '\n');
+  process.exit(1);
+}
+
+process.exit(cli.main(process.argv.slice(2)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -33,6 +33,7 @@
     "NOTICE"
   ],
   "bin": {
+    "gdd-detect": "./bin/gdd-detect",
     "gdd-events": "./scripts/cli/gdd-events.mjs",
     "gdd-graph": "./bin/gdd-graph",
     "gdd-mcp": "./bin/gdd-mcp",
@@ -57,6 +58,8 @@
     "lint:links": "npx --yes lychee --no-progress --accept 200,206,403,429 \"**/*.md\" || true",
     "lint:agentskills": "node scripts/lint-agentskills-spec.cjs",
     "lint:changelog": "node scripts/lint-changelog.cjs",
+    "lint:design": "node bin/gdd-detect test/fixtures/detect/negative --json",
+    "sync:rule-catalogue": "node scripts/sync-rule-catalogue.cjs --check",
     "validate:schemas": "node --experimental-strip-types scripts/validate-schemas.ts",
     "validate:frontmatter": "node --experimental-strip-types scripts/validate-frontmatter.ts agents/",
     "detect:stale-refs": "node scripts/detect-stale-refs.cjs",

package/reference/anti-patterns.md

@@ -18,6 +18,8 @@ Zero tolerance. Each violation = −3 points from Anti-Pattern score. Rewrite ra
 
 ### BAN-01: Side-Stripe Borders
 
+bdId: BAN-01
+
 ```css
 /* BANNED — AI-generated card tell, regardless of color */
 border-left: 4px solid var(--color-primary);
@@ -32,6 +34,8 @@ border-right: 3px solid #6366f1;
 
 ### BAN-02: Gradient Text
 
+bdId: BAN-02
+
 ```css
 /* BANNED */
 background: linear-gradient(to right, #6366f1, #8b5cf6);
@@ -48,6 +52,8 @@ background-clip: text;
 
 ### BAN-03: Bounce/Elastic Easing
 
+bdId: BAN-03
+
 ```css
 /* BANNED */
 transition: all 300ms cubic-bezier(0.68, -0.55, 0.265, 1.55);
@@ -63,6 +69,8 @@ animation-timing-function: spring(1, 80, 10, 0);
 
 ### BAN-04: Animating Keyboard Actions
 
+bdId: BAN-04
+
 No animation on: command palette open/close, keyboard shortcuts, tab switching, filter/sort toggles, navigation item expand/collapse.
 
 **Why**: These repeat 100+ times per day. Every millisecond of animation accumulates into felt sluggishness.
@@ -71,6 +79,8 @@ No animation on: command palette open/close, keyboard shortcuts, tab switching,
 
 ### BAN-05: Pure Black Dark Mode
 
+bdId: BAN-05
+
 ```css
 /* BANNED */
 background: #000000;
@@ -85,6 +95,8 @@ background: rgb(0, 0, 0);
 
 ### BAN-06: Disabling Zoom
 
+bdId: BAN-06
+
 ```html
 <!-- BANNED -->
 <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
@@ -97,6 +109,8 @@ background: rgb(0, 0, 0);
 
 ### BAN-07: Naked `outline: none`
 
+bdId: BAN-07
+
 ```css
 /* BANNED — unless a custom focus indicator replaces it */
 :focus { outline: none; }
@@ -111,6 +125,8 @@ button:focus { outline: 0; }
 
 ### BAN-08: `transition: all`
 
+bdId: BAN-08
+
 ```css
 /* BANNED */
 transition: all 300ms ease;
@@ -124,6 +140,8 @@ transition: all 300ms ease;
 
 ### BAN-09: `scale(0)` Animation Entry
 
+bdId: BAN-09
+
 ```css
 /* BANNED — nothing in the real world materializes from nothing */
 @keyframes enter { from { transform: scale(0); } }
@@ -339,6 +357,8 @@ If YES to any → rewrite that element before proceeding.
 
 ### BAN-10: Same Border-Radius on Nested Surfaces
 
+bdId: BAN-10
+
 Applying the same `border-radius` to a container and an element inside it (when the element is separated by padding) makes the inner element appear to "float" — the radii should be concentric, not equal.
 
 **Grep (Tailwind):**
@@ -355,6 +375,8 @@ Source: jakubkrehel/make-interfaces-feel-better (MIT)
 
 ### BAN-11: Tinted Image Outline
 
+bdId: BAN-11
+
 Using a colored outline on images (e.g., `outline-slate-200`, `outline-gray-300`, or a hex-value outline color) competes visually with the image content and creates color contamination.
 
 **Grep (Tailwind):**
@@ -376,6 +398,8 @@ Source: jakubkrehel/make-interfaces-feel-better (MIT)
 
 ### BAN-12: `transition: all`
 
+bdId: BAN-12
+
 `transition: all` animates every animatable CSS property on the element, including layout-triggering properties (width, height, padding, margin). This causes layout recalculation on EVERY transition, creating jank and unexpected visual effects (e.g., a hover transition that also animates the element's size if any dimensions change).
 
 **Grep (CSS):**
@@ -393,6 +417,8 @@ Source: jakubkrehel/make-interfaces-feel-better (MIT)
 
 ### BAN-13: `will-change: all`
 
+bdId: BAN-13
+
 `will-change: all` promotes every animatable property to its own GPU compositor layer, consuming GPU memory for each property. On complex components this can allocate hundreds of MB of texture memory per instance, causing performance degradation and potential crashes on mobile.
 
 **Grep:**

package/reference/cli-localization.md

@@ -0,0 +1,61 @@
+# CLI Localization — GDD's Own Surface
+
+Phase 40.5 contract. `reference/i18n.md` covers internationalizing *user designs*; this file covers
+**GDD's own CLI** — `--help`, the common error messages, and skill prompt headers. The goal is the
+lowest-effort, highest-impact subset; full skill-body translation is deferred (per-locale demand).
+
+## Resolution
+
+`scripts/lib/i18n/index.cjs` resolves the active locale with this precedence:
+
+1. **`.design/config.json#locale`** — an explicit per-project override (set via `/gdd:locale <code>`).
+2. **`process.env`** — `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE` (normalized: `ru_RU.UTF-8` → `ru`).
+3. **`en`** — the default.
+
+A `C` / `POSIX` env locale resolves to `en`. The resolved code then drives a **fallback chain**
+`locale → base → en` (e.g. `de-DE → de → en`), so a regional locale degrades to its base and finally
+to English — the complete source table.
+
+## Message tables
+
+Flat-JSON tables live at `scripts/lib/i18n/messages/<locale>.json` (chosen over ICU MessageFormat for
+simplicity). Each is `{ "_meta": { locale, coverage, fallback }, "<key>": "<string>", ... }`. Keys are
+namespaced: `help.*` (usage + section headers), `error.*` (the common CLI errors), `prompt.*` (skill
+prompt headers), `status.*`.
+
+- **`en.json`** — the **complete source of truth**; every key lives here.
+- **`ru.json`** — a complete second-locale translation (covers every `en` key).
+- **`uk.json` / `de.json` / `fr.json` / `zh.json` / `ja.json`** — **placeholders**: a `_meta` marker
+  (`coverage: "placeholder"`) plus a starter subset. Any missing key falls back to `en` per the chain.
+
+`translate(tables, key, locale)` walks the chain and returns the first hit, or the key itself if no
+table has it (a missing key is always visible, never a crash).
+
+## Frontmatter `description_i18n`
+
+Skills and agents may carry an **opt-in** `description_i18n: { <locale>: "<description>" }` map.
+`descriptionFor(frontmatter, locale)` returns the localized description via the fallback chain, or the
+plain English `description` when the locale is absent. The field is fully backward-compatible — a
+skill/agent without it is unaffected, and the Phase 28.5 contract only validates it (as an object of
+locale→string) when present.
+
+## Completeness policy
+
+The completeness gate is **warn-only**. Only `en` (source) and `ru` (full) are expected to be 100%; the
+five placeholder locales are intentionally partial and rely on the English fallback. A locale is never
+required to be complete to ship — partial is better than English-only, and fallback guarantees no key
+is ever missing at runtime.
+
+## Adding or completing a locale (contribution path)
+
+1. Edit `scripts/lib/i18n/messages/<locale>.json` — add the keys you can translate (any `en` key is
+   fair game; you do not need 100%).
+2. Set `_meta.coverage` to `"complete"` once every `en` key is present, else leave `"placeholder"`.
+3. Add a translator-credit line to `NOTICE` under the attributions section (name/handle + locale).
+4. Open a PR. The warn-only gate reports coverage; it does not block on partial locales.
+
+## Boundaries
+
+`--help` + common errors + skill prompt headers only — not full skill bodies (deferred per demand),
+not RTL terminal rendering (a terminal concern), not voice/conversational localization. English is
+always the final fallback, so the CLI is never broken by a partial translation.

package/reference/config-schema.md

@@ -395,3 +395,11 @@ single-operator projects are unaffected. Full contract: `reference/multi-author-
   team-mode policy (`scripts/lib/collab/lock-policy.cjs` — 30 s wait + 100 ms backoff);
   `sync_backend` selects the cross-machine `.design/` backend (`scripts/lib/collab/sync-backend.cjs`,
   default `git`; `s3`/`git-lfs` are opt-in declarations — a live client is not bundled this phase).
+
+## CLI localization (Phase 40.5)
+
+- **`locale`** (`en`|`ru`|`uk`|`de`|`fr`|`zh`|`ja`) — overrides the language of GDD's own `--help`,
+  common error messages, and skill prompt headers. Set via `/gdd:locale <code>`. Precedence: this key >
+  env `LANG`/`LC_ALL` > `en`. Missing message keys fall back to English (`scripts/lib/i18n/index.cjs`,
+  chain `locale → base → en`); `en` + `ru` are complete, the other five are placeholders. Full
+  contract: `reference/cli-localization.md`.

package/reference/registry.json

@@ -1035,6 +1035,13 @@
       "type": "meta-rules",
       "phase": 40,
       "description": "Phase 40 team-collaboration contract: multi-writer STATE.md via a git-merge-driver with per-section semantic merge (scripts/lib/collab/section-merge.cjs — union by D-id, conflict only on same-id divergence); decision attribution line-suffix [author= co-author=] (attribution.cjs); the async review queue proposed->reviewing->approved->locked with hard locks + audited /gdd:unlock-decision (review-queue.cjs); the multi-writer advisory-lock policy (lock-policy.cjs, 30s/100ms backoff in team mode); sectional handoff gdd_cycle_mode designer|dev|full (cycle-mode.cjs); the permission model (permissions.cjs) + CI gate; decision-journal-exporter (pseudonymized, write-only Notion) + pr-commenter D-XX threading; opt-in cross-machine sync (sync-backend.cjs, defaults to git). Agents conflict-resolver + decision-journal-exporter; skills /gdd:review-decisions + /gdd:unlock-decision."
+    },
+    {
+      "name": "cli-localization",
+      "path": "reference/cli-localization.md",
+      "type": "meta-rules",
+      "phase": 40.5,
+      "description": "Phase 40.5 CLI-localization contract: locale resolution (config.locale > env LANG > en) + fallback chain locale->base->en + flat-JSON message tables via scripts/lib/i18n/index.cjs; tables at scripts/lib/i18n/messages/{en,ru,uk,de,fr,zh,ja}.json (en source-complete, ru full, 5 placeholders with en fallback); the opt-in description_i18n frontmatter (descriptionFor falls back to English); /gdd:locale skill; warn-only completeness; the add-a-locale contribution path (translate table + NOTICE credit + PR). Distinct from reference/i18n.md (which covers USER-design i18n)."
     }
   ]
 }

package/reference/schemas/config.schema.json

@@ -41,6 +41,11 @@
       "type": "string",
       "description": "Latest plugin tag (e.g. \"v1.0.7.3\") whose update nudge the user has dismissed. Set by /gdd:check-update --dismiss and by hooks/update-check.sh on the --dismiss code path. When a newer tag ships, the nudge reappears."
     },
+    "locale": {
+      "type": "string",
+      "enum": ["en", "ru", "uk", "de", "fr", "zh", "ja"],
+      "description": "Phase 40.5 CLI locale override for GDD's own --help, error messages, and skill prompt headers. Set via /gdd:locale <code>. Precedence: this key > env LANG/LC_ALL > en. Missing message keys fall back to English per scripts/lib/i18n/index.cjs (locale -> base -> en). en + ru are complete; uk/de/fr/zh/ja are placeholders that fall back to English."
+    },
     "gdd_cycle_mode": {
       "type": "string",
       "enum": ["designer", "dev", "full"],

package/reference/schemas/generated.d.ts

@@ -101,6 +101,10 @@ export interface DesignConfigJson {
    * Latest plugin tag (e.g. "v1.0.7.3") whose update nudge the user has dismissed. Set by /gdd:check-update --dismiss and by hooks/update-check.sh on the --dismiss code path. When a newer tag ships, the nudge reappears.
    */
   update_dismissed?: string;
+  /**
+   * Phase 40.5 CLI locale override for GDD's own --help, error messages, and skill prompt headers. Set via /gdd:locale <code>. Precedence: this key > env LANG/LC_ALL > en. Missing message keys fall back to English per scripts/lib/i18n/index.cjs (locale -> base -> en). en + ru are complete; uk/de/fr/zh/ja are placeholders that fall back to English.
+   */
+  locale?: 'en' | 'ru' | 'uk' | 'de' | 'fr' | 'zh' | 'ja';
   /**
    * Phase 40 sectional handoff. designer = Brief + Explore only; dev = Plan + Design + Verify; full = all stages (default). scripts/lib/collab/cycle-mode.cjs gates STATE writes by stage so a designer and a dev can hand a cycle back and forth without overwriting each other's sections.
    */

package/scripts/lib/detect/cli.cjs

@@ -0,0 +1,111 @@
+'use strict';
+// Phase 41 — gdd-detect CLI. Dep-free by default (regex-fast). The DOM-aware (jsdom) and URL
+// (puppeteer) paths are SOFT optionals loaded via try-require — never a package.json dependency, so
+// the SC#10 network-isolation scan stays clean and the plugin keeps its zero-runtime-dep guarantee.
+//
+//   gdd-detect <path> [--json] [--fast] [--rule BAN-NN] [--puppeteer]
+//
+// Exit codes: 0 = clean · 2 = findings · 1 = invocation error.
+
+const engine = require('./engine.cjs');
+
+const HELP = `gdd-detect — scan HTML/CSS/JSX for GDD anti-patterns (BAN-NN).
+
+Usage:
+  gdd-detect <path> [options]
+
+Arguments:
+  <path>            A file or directory (scanned recursively), or a http(s):// URL (needs --puppeteer).
+
+Options:
+  --json            Machine-readable JSON output.
+  --fast            Regex-only; do not load jsdom even if present.
+  --rule <BAN-NN>   Run a single rule (e.g. --rule BAN-08).
+  --puppeteer       Allow scanning a URL via Puppeteer (an optional, separately-installed dependency).
+  -h, --help        This help.
+
+Exit codes: 0 clean · 2 findings · 1 invocation error.`;
+
+function parseArgs(argv) {
+  const opts = { path: null, json: false, fast: false, rule: null, puppeteer: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') opts.json = true;
+    else if (a === '--fast') opts.fast = true;
+    else if (a === '--puppeteer') opts.puppeteer = true;
+    else if (a === '-h' || a === '--help') opts.help = true;
+    else if (a === '--rule') opts.rule = argv[++i] || null;
+    else if (a.startsWith('--rule=')) opts.rule = a.slice('--rule='.length);
+    else if (!a.startsWith('-') && opts.path === null) opts.path = a;
+  }
+  return opts;
+}
+
+function isUrl(p) {
+  return /^https?:\/\//i.test(String(p || ''));
+}
+
+/** Select the detection engine. Returns { mode, warning }. Regex-fast is the dep-free default. */
+function selectEngine(opts, requireFn) {
+  if (opts.fast) return { mode: 'regex-fast', warning: null };
+  let hasJsdom = false;
+  try { requireFn('jsdom'); hasJsdom = true; } catch { hasJsdom = false; }
+  if (hasJsdom) return { mode: 'dom-aware', warning: null };
+  return { mode: 'regex-fast', warning: 'jsdom not installed — using regex-fast (install jsdom for DOM-aware mode, or pass --fast to silence this).' };
+}
+
+function renderHuman(result, mode) {
+  const lines = [];
+  for (const f of result.findings) {
+    lines.push(`${f.file}:${f.line}:${f.column}  ${f.severity.toUpperCase()}  ${f.ruleId} ${f.name} — ${f.references[0]}`);
+  }
+  const errs = result.findings.filter((f) => f.severity === 'error').length;
+  const warns = result.findings.length - errs;
+  lines.push('');
+  lines.push(`gdd-detect (${mode}): ${result.filesScanned} file(s), ${result.findings.length} finding(s) — ${errs} error, ${warns} warn.`);
+  return lines.join('\n');
+}
+
+/**
+ * @param {string[]} argv  process.argv.slice(2)
+ * @param {{ cwd?: string, log?: fn, err?: fn, requireFn?: fn }} [io]  injectable for tests
+ * @returns {number} exit code
+ */
+function main(argv, io) {
+  const o = io || {};
+  const log = o.log || ((s) => process.stdout.write(s + '\n'));
+  const err = o.err || ((s) => process.stderr.write(s + '\n'));
+  const requireFn = o.requireFn || require;
+  const cwd = o.cwd || process.cwd();
+  const opts = parseArgs(argv);
+
+  if (opts.help || (!opts.path && argv.length === 0)) { log(HELP); return opts.help ? 0 : 1; }
+  if (!opts.path) { err('gdd-detect: missing <path>. See --help.'); return 1; }
+  if (opts.rule && !/^BAN-\d{2}$/i.test(opts.rule)) { err(`gdd-detect: --rule expects a BAN-NN id (got "${opts.rule}").`); return 1; }
+
+  // URL path → Puppeteer (optional, separately installed). Never a stack trace.
+  if (isUrl(opts.path)) {
+    if (!opts.puppeteer) { err('gdd-detect: scanning a URL requires --puppeteer. Pass --puppeteer (and `npm i -D puppeteer`) to enable URL scans.'); return 1; }
+    let hasPuppeteer = false;
+    try { requireFn('puppeteer'); hasPuppeteer = true; } catch { hasPuppeteer = false; }
+    if (!hasPuppeteer) { err('gdd-detect: --puppeteer given but puppeteer is not installed. Install it with `npm i -D puppeteer` (it stays an optional dependency).'); return 1; }
+    err('gdd-detect: URL scanning is not wired in this build; clone the page locally and scan the files instead.');
+    return 1;
+  }
+
+  const { mode, warning } = selectEngine(opts, requireFn);
+  if (warning && !opts.json) err('gdd-detect: ' + warning);
+
+  let result;
+  try { result = engine.run(opts.path, { ruleId: opts.rule, cwd }); }
+  catch (e) { err('gdd-detect: ' + (e && e.message ? e.message : String(e))); return 1; }
+
+  if (opts.json) log(JSON.stringify({ mode, ...result }, null, 2));
+  else log(renderHuman(result, mode));
+
+  return result.findings.length > 0 ? 2 : 0;
+}
+
+module.exports = { main, parseArgs, isUrl, selectEngine, HELP };
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));