@hegemonart/get-design-done 1.48.0 → 1.49.0

package/hooks/gdd-design-quality-check.js

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * hooks/gdd-design-quality-check.js — advisory PostToolUse hook for the
+ * default-AI-aesthetic regex floor (Phase 49, Quick Anti-Slop Floor).
+ *
+ * The cheapest possible anti-slop pass: on every front-end file write, scan the
+ * written content for the visual tells that mark a UI as "an AI generated this"
+ * (gradient spam, the purple/violet default palette, glassmorphism stacks, the
+ * Inter default, centered-everything heroes, undraw/isometric clip art, filler
+ * CTA copy, decorative motion with no loading intent). Each match is a non
+ * blocking WARN. The catalog the rules come from lives at
+ * reference/visual-tells.md (8 named categories, 1:1 with the 8 rules here).
+ *
+ * Contract (mirrors hooks/gdd-a11y-gate.js):
+ *   - Read stdin JSON (the PostToolUse payload: {tool_name, tool_input,
+ *     tool_response, cwd, ...}).
+ *   - Only act on Write/Edit/MultiEdit tools targeting a .tsx/.vue/.svelte/.astro
+ *     file. Everything else is a bare {continue:true}.
+ *   - Scan the written content against 8 regex rules; collect matches as warnings.
+ *   - Emit one `design_quality_warn` event through scripts/lib/event-chain.cjs
+ *     (baseDir injected from cwd; the emit is best-effort and never fatal).
+ *   - Print a concise advisory to stdout and ALWAYS write {continue:true}, exit 0.
+ *     This hook is WARN-only. It never blocks a write.
+ *
+ * Dependency-free: core fs/path plus the in-repo event-chain helper. No npm deps.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Front-end source extensions this hook scans. */
+const FRONTEND_EXT = ['.tsx', '.vue', '.svelte', '.astro'];
+
+/**
+ * The 8 v1 rules. Each `category` matches a heading in reference/visual-tells.md.
+ * `test(content)` returns an array of { line, match } hits (possibly empty).
+ * Regexes are tuned for precision (low false-positive) over recall.
+ */
+
+/** Find the 1-based line number for a character offset in `content`. */
+function lineOf(content, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < content.length; i++) {
+    if (content[i] === '\n') line += 1;
+  }
+  return line;
+}
+
+/** Collect up to `cap` global-regex matches as {line, match}. */
+function collect(content, re, cap = 5) {
+  const hits = [];
+  let m;
+  re.lastIndex = 0;
+  while ((m = re.exec(content)) !== null) {
+    hits.push({ line: lineOf(content, m.index), match: m[0] });
+    if (m.index === re.lastIndex) re.lastIndex += 1; // zero-width guard
+    if (hits.length >= cap) break;
+  }
+  return hits;
+}
+
+/** Count global-regex matches without allocating the match list. */
+function countMatches(content, re) {
+  let n = 0;
+  let m;
+  re.lastIndex = 0;
+  while ((m = re.exec(content)) !== null) {
+    n += 1;
+    if (m.index === re.lastIndex) re.lastIndex += 1;
+  }
+  return n;
+}
+
+const RULES = [
+  {
+    rule: 'gradient-spam',
+    category: 'gradient-spam',
+    // >=3 Tailwind gradient-direction utilities in one file.
+    run(content) {
+      const re = /\bbg-gradient-to-(?:r|br|tr|b|bl|l|tl|t)\b/g;
+      const count = countMatches(content, re);
+      if (count < 3) return [];
+      const hits = collect(content, re, 5);
+      // Tag the first hit with the aggregate count for the advisory.
+      if (hits.length) hits[0].match = `${hits[0].match} (x${count})`;
+      return hits;
+    },
+  },
+  {
+    rule: 'generic-cta',
+    category: 'default-AI-hero',
+    // Filler hero / CTA copy. Word-boundaried, case-insensitive.
+    run(content) {
+      const re = /\b(?:Get Started|Welcome to|Lorem ipsum|Learn More)\b/gi;
+      return collect(content, re, 5);
+    },
+  },
+  {
+    rule: 'centered-everything-syndrome',
+    category: 'centered-everything-syndrome',
+    // mx-auto AND text-center co-occurring inside one className string.
+    run(content) {
+      // Match a quoted class string that contains both utilities, in either order.
+      const re =
+        /(["'`])(?=[^"'`]*\bmx-auto\b)(?=[^"'`]*\btext-center\b)[^"'`]*\1/g;
+      return collect(content, re, 5);
+    },
+  },
+  {
+    rule: 'inter-everything',
+    category: 'inter-everything',
+    // font-inter utility OR a font-family: Inter declaration, when no other
+    // custom font token (font-<name>, --font-*, or a second font-family) is near.
+    run(content) {
+      const interRe = /\bfont-inter\b|font-family:\s*['"]?Inter\b/gi;
+      const interCount = countMatches(content, interRe);
+      if (interCount === 0) return [];
+      // A sibling custom-font signal suppresses the warning (a deliberate stack).
+      const siblingFont =
+        /\bfont-(?!inter\b|sans\b|serif\b|mono\b|medium\b|semibold\b|bold\b|light\b|normal\b|thin\b|black\b|extrabold\b|extralight\b)[a-z]/i.test(
+          content,
+        ) ||
+        /--font-[a-z]/i.test(content) ||
+        /font-family:\s*['"]?(?!Inter\b)[A-Za-z]/i.test(content);
+      if (siblingFont) return [];
+      return collect(content, interRe, 5);
+    },
+  },
+  {
+    rule: 'purple-violet-default',
+    category: 'purple-violet-default',
+    // The default-AI palette bg-(purple|violet)-(500|600|700) with no theme
+    // token class (bg-primary / bg-brand / bg-accent / a CSS var) nearby.
+    run(content) {
+      const re = /\bbg-(?:purple|violet)-(?:500|600|700)\b/g;
+      if (countMatches(content, re) === 0) return [];
+      const themeToken =
+        /\bbg-(?:primary|brand|accent|surface|foreground|background|muted)\b/i.test(
+          content,
+        ) || /bg-\[(?:var\(--|hsl|oklch|rgb)/i.test(content);
+      if (themeToken) return [];
+      return collect(content, re, 5);
+    },
+  },
+  {
+    rule: 'glassmorphism-spam',
+    category: 'glassmorphism-spam',
+    // >=3 of backdrop-blur* / bg-white/(10|20|30) in one file.
+    run(content) {
+      const re = /\bbackdrop-blur(?:-\w+)?\b|\bbg-white\/(?:10|20|30)\b/g;
+      const count = countMatches(content, re);
+      if (count < 3) return [];
+      const hits = collect(content, re, 5);
+      if (hits.length) hits[0].match = `${hits[0].match} (x${count})`;
+      return hits;
+    },
+  },
+  {
+    rule: 'isometric-illustration-fallback',
+    category: 'isometric-illustration-fallback',
+    // undraw / isometric markers in an asset path or src attribute.
+    run(content) {
+      const re = /\b(?:undraw|isometric)[\w./-]*/gi;
+      return collect(content, re, 5);
+    },
+  },
+  {
+    rule: 'decorative-motion-without-intent',
+    category: 'decorative-motion-without-intent',
+    // animate-(pulse|bounce|spin) on a non-loading, non-icon element.
+    // Conservative: only flag a className that has the animate utility but no
+    // loading/skeleton/spinner/icon signal on the same class string.
+    run(content) {
+      const re =
+        /(["'`])(?=[^"'`]*\banimate-(?:pulse|bounce|spin)\b)(?![^"'`]*(?:\b(?:animate-(?:pulse|bounce|spin)\s+)?(?:loading|loader|spinner|skeleton|icon|i-)\b|sr-only))[^"'`]*\1/g;
+      return collect(content, re, 5);
+    },
+  },
+];
+
+/**
+ * Resolve the written content from a PostToolUse payload, tolerating Write
+ * (tool_input.content), Edit (new_string), and MultiEdit (edits[].new_string),
+ * and falling back to a tool_response filePath/content when present.
+ *
+ * Returns { filename, content } or null when there is nothing front-end to scan.
+ */
+function extractWrite(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  const tool = payload.tool_name || payload.toolName;
+  if (tool !== 'Write' && tool !== 'Edit' && tool !== 'MultiEdit') return null;
+
+  const input = payload.tool_input || payload.toolInput || {};
+  const filename =
+    input.file_path ||
+    input.filePath ||
+    input.path ||
+    (payload.tool_response &&
+      (payload.tool_response.filePath || payload.tool_response.file_path)) ||
+    '';
+  if (!filename) return null;
+
+  const ext = path.extname(String(filename)).toLowerCase();
+  if (!FRONTEND_EXT.includes(ext)) return null;
+
+  const parts = [];
+  if (typeof input.content === 'string') parts.push(input.content);
+  if (typeof input.new_string === 'string') parts.push(input.new_string);
+  if (Array.isArray(input.edits)) {
+    for (const e of input.edits) {
+      if (e && typeof e.new_string === 'string') parts.push(e.new_string);
+    }
+  }
+  // Fall back to a post-write file content echo if the input carried none.
+  if (parts.length === 0 && payload.tool_response) {
+    const tr = payload.tool_response;
+    if (typeof tr.content === 'string') parts.push(tr.content);
+  }
+
+  const content = parts.join('\n');
+  if (!content) return null;
+  return { filename: String(filename), content };
+}
+
+/**
+ * Pure evaluator: scan `content` (with `filename` for category context) against
+ * the 8 rules. Exported for unit testing without a process.
+ *
+ * @returns {{ warnings: Array<{rule, category, line, match}>, count: number }}
+ */
+function evaluate(content, filename) {
+  const warnings = [];
+  if (typeof content !== 'string' || content.length === 0) {
+    return { warnings, count: 0 };
+  }
+  for (const r of RULES) {
+    let hits = [];
+    try {
+      hits = r.run(content) || [];
+    } catch {
+      hits = []; // a misbehaving rule must never break the advisory
+    }
+    for (const h of hits) {
+      warnings.push({
+        rule: r.rule,
+        category: r.category,
+        line: h.line,
+        match: h.match,
+      });
+    }
+  }
+  return { warnings, count: warnings.length };
+}
+
+/** Best-effort event emit through the in-repo event-chain helper. Never throws. */
+function emitEvent(cwd, filename, result) {
+  try {
+    const { appendChainEvent } = require('../scripts/lib/event-chain.cjs');
+    appendChainEvent({
+      agent: 'gdd-design-quality-check',
+      outcome: 'warn',
+      event: 'design_quality_warn',
+      file: filename,
+      warning_count: result.count,
+      categories: [...new Set(result.warnings.map((w) => w.category))],
+      warnings: result.warnings.slice(0, 20),
+      baseDir: cwd,
+    });
+  } catch {
+    /* observability is best-effort — swallow */
+  }
+}
+
+/** Build the concise stdout advisory string for a non-empty result. */
+function advisoryNote(filename, result) {
+  const cats = [...new Set(result.warnings.map((w) => w.category))];
+  const base = path.basename(filename);
+  const lines = [
+    `gdd-design-quality-check: ${result.count} visual-tell ` +
+      `warning${result.count === 1 ? '' : 's'} in ${base} ` +
+      `across ${cats.length} categor${cats.length === 1 ? 'y' : 'ies'} ` +
+      `(${cats.join(', ')}).`,
+  ];
+  for (const w of result.warnings.slice(0, 8)) {
+    lines.push(`  - [${w.rule}] line ${w.line}: ${w.match}`);
+  }
+  lines.push('  See reference/visual-tells.md for remediation patterns. (advisory, non-blocking)');
+  return lines.join('\n');
+}
+
+/**
+ * Core hook entry. Accepts a parsed payload, returns the decision object to
+ * write to stdout. Always returns { continue: true } (advisory only).
+ * Exported for unit testing without spawning a process.
+ */
+function main(payload, opts = {}) {
+  const cwd = (payload && payload.cwd) || opts.cwd || process.cwd();
+  const write = extractWrite(payload);
+  if (!write) return { continue: true };
+
+  const result = evaluate(write.content, write.filename);
+  if (result.count === 0) return { continue: true };
+
+  emitEvent(cwd, write.filename, result);
+  const note = advisoryNote(write.filename, result);
+  return { continue: true, systemMessage: note };
+}
+
+async function run(stdin = process.stdin, stdout = process.stdout) {
+  let buf = '';
+  for await (const chunk of stdin) buf += chunk;
+  let payload;
+  try {
+    payload = JSON.parse(buf || '{}');
+  } catch {
+    stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+  const decision = main(payload);
+  if (decision.systemMessage) {
+    // Surface the advisory on stderr too so it is visible in plain hook logs.
+    try {
+      process.stderr.write(decision.systemMessage + '\n');
+    } catch {
+      /* swallow */
+    }
+  }
+  stdout.write(JSON.stringify(decision));
+}
+
+// Run as a CLI only when invoked directly; tests require() this module and call
+// evaluate()/main() against mock payloads without triggering stdin reads.
+if (require.main === module) {
+  run().catch(() => {
+    process.stdout.write(JSON.stringify({ continue: true }));
+  });
+}
+
+module.exports = { main, evaluate, extractWrite, RULES, FRONTEND_EXT };

package/hooks/hooks.json

@@ -124,6 +124,15 @@
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-a11y-gate.js\""
           }
         ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-design-quality-check.js\""
+          }
+        ]
       }
     ],
     "Stop": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.48.0",
+  "version": "1.49.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",
@@ -115,7 +115,10 @@
     "agent-sdk",
     "figma",
     "extractor",
-    "design-system-sync"
+    "design-system-sync",
+    "worktree-safe",
+    "anti-slop",
+    "confidence-gate"
   ],
   "skills": [
     "SKILL.md"

package/reference/registry.json

@@ -1121,6 +1121,20 @@
       "type": "output-contract",
       "phase": 48,
       "description": "Phase 48 brief-quality rubric: 5 anti-patterns (vague verbs, missing audience, immeasurable success criteria, scope creep, missing anti-goals) the brief-auditor surfaces."
+    },
+    {
+      "name": "visual-tells",
+      "path": "reference/visual-tells.md",
+      "type": "heuristic",
+      "phase": 49,
+      "description": "Phase 49 visual-tells catalog: 8 default-AI-aesthetic categories (default-AI-hero, gradient-spam, isometric-illustration-fallback, centered-everything-syndrome, inter-everything, purple-violet-default, glassmorphism-spam, decorative-motion-without-intent) with diagnostic regex + remediation; backs the gdd-design-quality-check hook."
+    },
+    {
+      "name": "reviewer-confidence-gate",
+      "path": "reference/reviewer-confidence-gate.md",
+      "type": "meta-rules",
+      "phase": 49,
+      "description": "Phase 49 reviewer confidence gate: 4-question Pre-Report Gate + confidence 0.0-1.0 field; HIGH/CRITICAL require >=0.8 + cited proof, <0.5 stays Tentative and never reaches design-fixer."
     }
   ]
 }

package/reference/reviewer-confidence-gate.md

@@ -0,0 +1,108 @@
+---
+name: reviewer-confidence-gate
+type: meta-rules
+version: 1.0.0
+phase: 49
+tags: [review, confidence, audit, verify, gap, routing, anti-slop]
+last_updated: 2026-06-03
+---
+
+# Reviewer Confidence Gate
+
+Audit and verify findings can inflate severity without proof. A grep hit gets reported as a BLOCKER; a single line read out of context becomes a MAJOR. This contract adds a confidence discipline so review agents (`design-auditor`, `design-verifier`, `design-debt-crawler`) earn the severity they assign, and so `design-fixer` only auto-applies fixes that are backed by evidence.
+
+Every emitting agent runs the Pre-Report Gate before writing a finding, stamps each finding with a `confidence` score, and parks weak findings in a `## Tentative` section that the fixer never reads. The routing helper `scripts/lib/confidence-route.cjs` encodes the same rule in code.
+
+## Pre-Report Gate
+
+Before you emit any finding or gap, answer these four questions. If you cannot answer all four with a clear yes, the finding is not ready to ship at its stated severity.
+
+- **a. Can I cite `file:line`?** Point at the exact location. A finding with no concrete location is a hunch, not a defect.
+- **b. Can I state the failure mode in one sentence?** Name what breaks for the user or the build. If the sentence needs an "and" plus a "maybe", the finding is two findings or none.
+- **c. Did I read context beyond the modified file?** Confirm the call site, the token definition, or the parent component. A value that looks wrong in isolation is often correct once you read what feeds it.
+- **d. Is the severity defensible?** A BLOCKER blocks shipping. A MAJOR is a real deviation from intent. If you would not defend the label to the author, lower it.
+
+## The `confidence` field
+
+Every finding carries a `confidence: 0.0-1.0` field. It records how sure you are that the finding is real and correctly classified, not how bad the issue is. Severity and confidence are independent axes: a cosmetic issue can be high confidence, and a suspected BLOCKER can be low confidence.
+
+| Range | Meaning | Where it goes |
+|-------|---------|---------------|
+| `>= 0.8` | Cited `file:line`, one-sentence failure mode, context read. | Reported at full severity; eligible for auto-fix. |
+| `0.5 - 0.8` | Real signal, but evidence is partial or context is incomplete. | Reported, routed to user review, never auto-fixed. |
+| `< 0.5` | A hunch, a guess, or a pattern match you could not confirm. | Moved to `## Tentative`; never reaches `design-fixer`. |
+
+## Routing rule
+
+The gate controls what reaches the fixer. The rule is:
+
+- A HIGH severity finding (BLOCKER or MAJOR) requires `confidence >= 0.8` **and** a `file:line` citation **and** a one-sentence failure mode. Below `0.8`, a HIGH finding is surfaced for user review instead of auto-fix.
+- A finding with `confidence < 0.5` stays in the `## Tentative` section and never reaches `design-fixer`.
+- A finding with `confidence` in the `0.5 - 0.8` band is surfaced in the report but routed to user review, not auto-fix.
+
+`scripts/lib/confidence-route.cjs` exports `route({ severity, confidence, tentative })` and returns `'fix'`, `'user-review'`, or `'drop'`. Agents and the fixer share this single decision so the matrix stays consistent.
+
+### Routing matrix
+
+The full decision table the helper encodes:
+
+| Severity | `tentative` | confidence | Destination |
+|----------|-------------|------------|-------------|
+| any | `true` | any | `drop` (never reaches fixer) |
+| any | `false` | `< 0.5` | `drop` (stays tentative) |
+| BLOCKER or MAJOR | `false` | `0.5 - 0.8` | `user-review` |
+| BLOCKER or MAJOR | `false` | `>= 0.8` | `fix` |
+| MINOR or COSMETIC | `false` | `0.5 - 0.8` | `user-review` |
+| MINOR or COSMETIC | `false` | `>= 0.8` | `fix` |
+
+Read the table as: tentative wins first, then the `0.5` floor, then the severity-specific `0.8` auto-fix gate.
+
+## How to emit a finding
+
+After the Pre-Report Gate passes, write the finding with the `confidence` field on its own line inside the existing locked format. For `design-verifier` gaps this sits alongside the other gap fields:
+
+```text
+### BLOCKER G-01: raw error object rendered on payment failure
+- Phase: 2
+- Description: Checkout.tsx renders the error object directly
+- Expected: a human-readable failure message
+- Actual: users see "[object Object]"
+- Location: src/Checkout.tsx:88
+- Suggested fix: render error.message with a fallback string
+- confidence: 0.85
+```
+
+A finding that scores `< 0.5` is not written in the gap list at all. It goes under a `## Tentative` heading in the same report, in plain prose, so a human can promote it later if context proves it real.
+
+## Paired examples
+
+Each pair shows a raw finding (before the gate) and the same finding after the gate corrects it.
+
+### Example 1: severity inflated, no context read
+
+**Before:** `BLOCKER: hardcoded color #1a73e8 in Button.tsx breaks theming.`
+
+**After:** `MINOR G-04: raw #1a73e8 instead of a semantic token. confidence: 0.9`. Reading context (question c) showed `Button.tsx:42` is the token definition file, so theming is not broken; the issue is a style-coherence nit, not a shipping blocker. High confidence, low severity.
+
+### Example 2: a grep guess that could not be confirmed
+
+**Before:** `MAJOR: missing reduced-motion guard, animations will trigger vestibular issues.`
+
+**After:** moved to `## Tentative` with `confidence: 0.4`. The grep matched `framer-motion` but question a failed: no single `file:line` proves the guard is absent app-wide, and a root `MotionConfig` may cover it. Parked as tentative; the fixer never sees it.
+
+### Example 3: real defect, evidence complete
+
+**Before:** `error states look weak somewhere in the checkout flow.`
+
+**After:** `BLOCKER G-01: Checkout.tsx:88 renders the raw error object, so users see "[object Object]" on a failed payment. confidence: 0.85`. All four questions pass: cited location, one-sentence failure mode, call site read, severity defensible. Auto-fix eligible.
+
+### Example 4: partial evidence, honest mid-band score
+
+**Before:** `MAJOR: empty state copy is generic across the app.`
+
+**After:** `MINOR G-06: Inbox.tsx:30 empty state reads "No data". confidence: 0.65`. One real instance is cited, but question c is only half done: the "across the app" claim was not verified. Scored mid-band, surfaced for user review rather than auto-fixed, and the severity was lowered to match the single confirmed instance.
+
+## Agent integration
+
+- `design-auditor`, `design-verifier`, and `design-debt-crawler` run the Pre-Report Gate, stamp each finding with `confidence`, and route sub-0.5 findings to `## Tentative`.
+- `design-fixer` skips every gap in `## Tentative` and skips BLOCKER or MAJOR gaps whose `confidence < 0.8`, routing those to user review instead of auto-fix.