@hegemonart/get-design-done 1.40.5 → 1.41.5

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.5"
+    "version": "1.41.5"
   },
   "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.5",
+      "version": "1.41.5",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.40.5",
+  "version": "1.41.5",
   "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,86 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.41.5] - 2026-06-02
+
+### Phase 41.5 — SoT Manifest Consolidation
+
+A 2026-05-16 audit found Phase 42/44/45/47 each scoping its own "single source of truth" in a different
+corner — four formats, four schemas, four CI drift gates. 41.5 lands **one** root, **one** schema
+directory, **one** validator, **before** those phases plan their work. **No new runtime dependency, no
+new egress.**
+
+### Added
+
+- **`scripts/lib/manifest/`** — the cross-phase SoT root:
+  - `loader.cjs` — the one shared reader; a missing/unparseable file returns an empty fallback + a
+    one-line warning (never throws), with a file-mtime cache. Dep-free.
+  - `index.cjs` — typed readers `readHarnesses()` / `readSkills()` / `readProseDenylist()`.
+  - `harnesses.json` (+ `.cjs` view) — the 14 canonical runtimes (Phase 42 adds build config, Phase 45
+    the capability matrix, as views of this one record). `skills.json` — the 83 live skill names (Phase
+    47 enriches). `prose-denylist.json` — the AI-tell denylist + em-dash/`--` markers (Phase 43/44 consume).
+  - `schemas/*.schema.json` — one JSON Schema per manifest. `README.md` — the contract + migration note.
+- **`scripts/validate-manifest.cjs`** (`npm run validate:manifest`) — the single ajv CI gate that
+  replaces the four per-file drift gates 43/44/45/47 would each have shipped.
+
+### Notes
+
+- **No new runtime dependency** — the shipped `loader.cjs`/`index.cjs` are dep-free; `validate-manifest.cjs`
+  uses the already-present `ajv` and is maintainer-only (not shipped, like `lint-changelog.cjs`).
+- 6-manifest lockstep at **v1.41.5** + `OFF_CADENCE_VERSIONS.add('1.41.5')` + the 36 live-pinned
+  `manifests-version.txt` baselines forward-propagated 1.41.0 → 1.41.5.
+- Inventory: tarball golden 747 → 757 (+10: `scripts/lib/manifest/**`). No skill/agent/registry deltas.
+
+---
+
+## [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

package/README.md

@@ -198,6 +198,10 @@ GDD's single-operator baseline now extends to **teams** — git-native + advisor
 
 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/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.5",
+  "version": "1.41.5",
   "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,9 @@
     "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:manifest": "node scripts/validate-manifest.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/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)));

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,
+};