chati-dev 4.1.4 → 4.1.6

package/bin/chati.js

@@ -105,6 +105,16 @@ async function main() {
 
       console.log(`  ${migrationResult.migrationsRun} migration(s) applied.`);
 
+      // 2.5. Sync framework files (copy new/updated agents, templates, hooks, etc.)
+      console.log('  Syncing framework files...');
+      try {
+        const { copyFrameworkFiles } = await import('../src/installer/core.js');
+        copyFrameworkFiles(join(targetDir, 'chati.dev'));
+        console.log('  Framework files synced.');
+      } catch (err) {
+        console.log(`  Framework sync skipped: ${err.message}`);
+      }
+
       // 3. Validate
       console.log('  Validating...');
       const validation = await validateInstallation(targetDir);

package/framework/agents/build/dev.md

@@ -39,8 +39,12 @@ Implement each task from the approved task breakdown with high quality, followin
 3. Read Tasks: `chati.dev/artifacts/6-Tasks/tasks.md`
 4. Read Architecture: `chati.dev/artifacts/3-Architecture/architecture.md`
 5. Read UX: `chati.dev/artifacts/4-UX/ux-specification.md` (Design System tokens)
-6. Read Intelligence: `chati.dev/intelligence/gotchas.yaml` (known pitfalls)
-7. Acknowledge inherited context
+6. Read Brandbook: `chati.dev/artifacts/4-UX/brandbook.md` (visual identity, token values)
+7. Read Intelligence: `chati.dev/intelligence/gotchas.yaml` (known pitfalls)
+8. If browser MCP available: open `chati.dev/artifacts/4-UX/brandbook.html` in browser
+   via `browser_navigate` and take a screenshot to establish visual reference baseline.
+   If not available: skip silently, rely on brandbook.md text values only.
+9. Acknowledge inherited context
 
 **Agent-Driven Opening:**
 > "QA-Planning approved the plan. I'll now implement the tasks starting with Phase 1.
@@ -89,6 +93,24 @@ For each task:
      RULE: architecture.md is the source of truth. NEVER implement against architectural decisions.
      RULE: Do NOT silently reconcile conflicts — always surface them.
      If no architecture.md present → proceed with best practices, note in handoff.
+  2.5. Component Research (MANDATORY for any task that creates or modifies a UI component):
+     BEFORE writing any UI code, search production component libraries:
+
+     a. WebFetch `https://ui.shadcn.com/r/{component-name}.json` — structural components
+     b. WebFetch `https://21st.dev/r/{component-slug}` — animated/styled components
+     c. WebFetch `https://magicui.design/r/{component-name}` — effects, backgrounds, text animations
+     d. Check Aceternity UI (`https://ui.aceternity.com`) — landing pages, 3D cards, spotlight effects
+     e. Check React Bits (`https://reactbits.dev`) — interactive animated components
+
+     Decision:
+       ADOPT: use component code as-is, adapt tokens to project values
+       ADAPT: use structure, replace visual values with project tokens
+       CUSTOM: build from scratch (only if nothing suitable in any library)
+
+     Log in task output: "Component source: {ADOPTED/ADAPTED/CUSTOM} from {source}/{name}"
+     If WebFetch unavailable: log "Research skipped — unavailable" and proceed.
+     Skip entirely for backend-only, config, or test-only tasks.
+
   3. Implement code
      -> Output: "Implementation done. Running self-critique (5.5)..."
   4. Run self-critique (Step 5.5) — 1 fix pass, then proceed
@@ -116,7 +138,24 @@ For each task:
             [ ] No console.log (use proper logging)
             [ ] No commented-out code
             [ ] Commit message follows conventional format
+            [ ] Visual review passed (Step 9.7) — UI tasks only
      If ANY item fails: fix before committing.
+  9.7. Visual Self-Review (MANDATORY for tasks that touch UI files):
+     Skip entirely for backend-only, config, or test-only tasks.
+
+     a. Ensure dev server is running (start with `npm run dev` if needed).
+     b. Use Playwright MCP: `browser_navigate` to the affected page.
+     c. Take screenshot: `browser_take_screenshot`
+     d. Analyze screenshot against:
+        - Brandbook tokens: colors, spacing, typography visually matching?
+        - Component states: default, hover, error, loading states correct?
+        - Layout integrity: no broken layouts, overflow, or misalignment?
+     e. If visual issues found: fix (1 pass only), re-screenshot.
+     f. Output: "Visual review PASSED — screenshot attached"
+        Or: "Visual review DEFERRED — browser MCP unavailable"
+
+     If browser MCP unavailable: mark DEFERRED, note in handoff. Do NOT block.
+
   10. Commit and move to next task
 
 ANTI-LOOP RULE: Steps 5.5 and 6.5 execute ONCE per task. No cycles allowed.
@@ -154,6 +193,11 @@ WHILE tasks_pending:
          → API/DB/Auth/module tasks: verify patterns match architecture.md
          → If conflict → mark task blocked (G05), skip to next task
          → If no architecture.md → proceed with best practices
+    2.5. Component Research (UI tasks only — same rules as Interactive Mode):
+         → WebFetch shadcn/ui, 21st.dev, Magic UI, Aceternity UI, React Bits
+         → ADOPT/ADAPT if match found; CUSTOM only as last resort
+         → Log: "Component source: {status} [{source}]"
+         → If unavailable: log "Research skipped" and proceed
     3. Implement code
        -> Output: "T{X} implementation done. Self-critique (5.5)..."
     4. Run self-critique (Step 5.5) — 1 fix pass, then proceed
@@ -163,6 +207,10 @@ WHILE tasks_pending:
     6. Run post-test critique (Step 6.5) — 1 fix pass, then score
        -> Output: "T{X} review done. Scoring..."
     7. Self-validate against acceptance criteria
+    7.5. Visual Self-Review (UI tasks only — same rules as Interactive Mode Step 9.7):
+         → browser_navigate to affected page, browser_take_screenshot
+         → Analyze vs brandbook + spec. Fix (1 pass) if issues found, re-screenshot
+         → If browser MCP unavailable: mark DEFERRED in handoff
     8. Calculate score
 
     IF score >= 95:

package/framework/agents/plan/ux-component-engineer.md

@@ -54,39 +54,72 @@ For each component specify:
 - Props interface (what data it accepts)
 - Token dependencies (which design tokens it uses)
 
-### 3C. Component Discovery (21st.dev)
+### 3C. Component Discovery
 
-BEFORE designing any Molecule or Organism from scratch, search 21st.dev for existing
-production-ready components that can be adapted.
+BEFORE designing any Molecule or Organism from scratch, search production component libraries
+in priority order. Use WebFetch to pull registry JSON and inspect actual component source.
 
 **Component Library Strategy** (verified, scrapable sources):
 
 Primary: Shadcn/ui (MIT license, React + Radix UI + Tailwind + cva)
-  - Registry: ui.shadcn.com (component docs with code examples)
-  - GitHub: github.com/shadcn-ui/ui (source code, fully scrapable)
+  - Registry JSON: WebFetch `https://ui.shadcn.com/r/{component-name}.json`
+    (returns full component source + dependencies)
+  - GitHub: github.com/shadcn-ui/ui
   - Components: Button, Input, Select, Dialog, Sheet, Table, Card, Tabs, Command, etc.
 
-Secondary: Headless UI (Tailwind Labs, MIT license)
+Secondary: 21st.dev (community-built, animated, high-quality React/Tailwind)
+  - Registry JSON: WebFetch `https://21st.dev/r/{component-slug}`
+    (slug = kebab-case, e.g. "animated-hero", "pricing-cards", "feature-grid")
+  - Strength: production-quality animated components, scroll effects, modern layouts
+  - License: varies per component — check the registry JSON "license" field before adopting
+
+Tertiary: Magic UI (150+ MIT components, animated effects)
+  - Registry JSON: WebFetch `https://magicui.design/r/{component-name}`
+    (returns full TSX source — examples: "animated-beam", "border-beam", "globe",
+     "morphing-text", "retro-grid", "shimmer-button", "aurora-text")
+  - Strength: animated effects, background patterns, text animations
+
+Quaternary: Aceternity UI (200+ free components, Framer Motion animations)
+  - Website: `https://ui.aceternity.com`
+  - Strength: spotlight effects, parallax scrolling, 3D cards, animated layouts
+  - Best for: landing pages, hero sections, feature showcases, pricing tables
+  - License: check per component before adopting
+
+Quinary: React Bits (animated, interactive React components)
+  - Website: `https://reactbits.dev`
+  - Strength: high-quality animated interactive components, unique micro-interactions
+  - Best for: interactive elements, animated lists, creative UI patterns
+
+Senary: Headless UI (Tailwind Labs, MIT license)
   - GitHub: github.com/tailwindlabs/headlessui
   - Unstyled primitives: Menu, Listbox, Combobox, Dialog, Popover, Switch, Tabs
-
-Tertiary: Custom build (when no suitable library component exists)
-
-For EACH Molecule and Organism:
-1. Check Shadcn/ui registry for matching component
-   - If found: ADOPTED (use pattern as-is) or ADAPTED (modify to fit project tokens)
-2. If not in Shadcn: check Headless UI
-3. If neither: CUSTOM with documented rationale
-
-Matching criteria:
-  (a) Supports required variants (primary/secondary/ghost/destructive)
-  (b) Includes keyboard navigation (Tab, Enter, Escape, Arrow keys)
+  - Use when: accessibility-critical component, no styled match found above
+
+Last resort: Custom build (when no suitable library component exists)
+
+**Discovery Process** (MANDATORY for each Molecule and Organism):
+1. Identify the component need from user flows
+2. WebFetch shadcn/ui: `https://ui.shadcn.com/r/{name}.json` — structural match
+3. WebFetch 21st.dev: `https://21st.dev/r/{name}` — animated/styled match
+4. WebFetch Magic UI: `https://magicui.design/r/{name}` — effect/enhancement match
+5. Check Aceternity UI and React Bits websites for specialized components (landing pages, interactive elements)
+6. If still not found: check Headless UI GitHub for primitive
+7. If nothing suitable: CUSTOM
+
+Matching criteria (any source):
+  (a) Supports required variants from component spec
+  (b) Has keyboard navigation (Tab, Enter, Escape, Arrow keys)
   (c) Has TypeScript types
   (d) Accessible by default (ARIA attributes, focus management)
   (e) Compatible with frontend framework from Architecture
+  (f) License is MIT or permissive (do NOT adopt GPL or unlicensed components)
 
 **Component Discovery Log** (MANDATORY):
-Every Molecule and Organism MUST have an entry with status (ADOPTED/ADAPTED/CUSTOM).
+Every Molecule and Organism MUST have an entry:
+| Component | Source Library | URL Fetched | Status | Notes |
+|-----------|---------------|-------------|--------|-------|
+| {Name} | {shadcn/21st.dev/magicui/headless/custom} | {url} | {ADOPTED/ADAPTED/CUSTOM} | {rationale} |
+
 Missing entries = FAIL for self-validation criterion.
 Zero silent skips.
 
@@ -188,11 +221,47 @@ Report: contrast ratio table with APCA Lc values for all color pairs, focus orde
 
 Define professional animation by default:
 
-**Library Selection** (by frontend framework from Architecture):
-- React/Next.js: `motion/react` (formerly framer-motion)
-- Vue/Nuxt: `@vueuse/motion`
-- Svelte: built-in transitions
-- Vanilla: `gsap` or Web Animations API
+**Animation Library Selection** (by frontend framework from Architecture):
+
+| Framework | Primary (micro-interactions) | Complex animations | Scroll |
+|-----------|----------------------------|-------------------|--------|
+| React/Next.js | `motion/react` | `anime.js` or `gsap` | `lenis` + `gsap ScrollTrigger` |
+| Vue/Nuxt | `@vueuse/motion` | `anime.js` or `gsap` | `lenis` + `gsap ScrollTrigger` |
+| Svelte | built-in transitions | `anime.js` or `gsap` | `lenis` |
+| Vanilla | Web Animations API | `gsap` | `lenis` + `gsap ScrollTrigger` |
+
+**motion/react** (primary for React, 8KB):
+  - Default for: hover, focus, click feedback, layout transitions, page transitions
+  - Declarative API integrates with React component lifecycle
+  - Do NOT use for: complex multi-element timelines or scroll-driven sequences
+
+**GSAP** (`npm i gsap`, industry standard, now 100% free):
+  - Use when: complex timelines, ScrollTrigger (scroll-driven animations),
+    SVG morphing, text splitting, pinning sections during scroll
+  - ScrollTrigger: `gsap.registerPlugin(ScrollTrigger)` — the gold standard for scroll animations
+  - Best for: landing pages, scrollytelling, parallax, section-based reveals
+  - API: `gsap.to('.element', { y: -20, duration: 0.6, ease: 'power2.out' })`
+
+**anime.js** (`npm i animejs`, 24.5KB, zero deps, MIT license):
+  - Use when: staggered entrance sequences, counter/number animations,
+    spring physics stagger, SVG path drawing
+  - Lighter than GSAP, simpler API for non-scroll animations
+  - API: `anime({ targets, translateY, opacity, delay, easing, duration })`
+  - Timeline: `anime.timeline({ autoplay: false }).add(...).add(...)`
+
+**Lenis** (`npm i lenis`, smooth scroll):
+  - Use when: the design requires buttery-smooth momentum scrolling
+  - Does NOT break CSS sticky positioning (unlike other smooth scroll libs)
+  - Pairs perfectly with GSAP ScrollTrigger for scroll-driven animations
+  - API: `const lenis = new Lenis(); lenis.on('scroll', ScrollTrigger.update)`
+
+**Decision rules:**
+  - Simple hover/focus/click → motion/react (default)
+  - Scroll-driven reveals, parallax, pinning → GSAP ScrollTrigger + Lenis
+  - Staggered lists, counters, SVG drawing → anime.js
+  - Smooth page scroll → Lenis
+  - Page/layout transitions → motion/react
+  - Do NOT combine motion/react with GSAP on the same element (conflict)
 
 **Motion Personality** (from brandbook motion philosophy):
 - Energetic: fast reveals, staggered entries, marquee effects
@@ -278,7 +347,7 @@ Missing states = quality regression. No happy-path-only components.
 3. All interactive components specify full state coverage (interactive + input + data view + page)
 4. All animations use GPU-only properties with reduced-motion alternatives
 5. Motion System defined (library, tokens, micro-interactions, scroll animations)
-6. Component Discovery Log complete (EVERY Molecule + Organism has entry with ADOPTED/ADAPTED/CUSTOM status)
+6. Component Discovery Log complete (EVERY Molecule + Organism has entry): all 3 registry sources queried (shadcn/ui, 21st.dev, Magic UI), status ADOPTED/ADAPTED/CUSTOM with source URL, license verified
 
 ---
 

package/framework/agents/quality/qa-implementation.md

@@ -18,9 +18,9 @@ You are the **QA-Implementation Agent**, the quality gate between BUILD and DEPL
 
 ## Required MCPs
 - git (read-only)
+- browser (Playwright MCP — required for visual review of UI changes)
 
 ## Optional MCPs
-- browser (for E2E testing)
 - coderabbit (AI-powered code review)
 
 ---
@@ -37,7 +37,9 @@ Validate that the implemented code meets quality standards: tests pass, coverage
 2. Read `.chati/session.yaml` for project context
 3. Read Tasks: `chati.dev/artifacts/6-Tasks/tasks.md` (acceptance criteria)
 4. Read Architecture: `chati.dev/artifacts/3-Architecture/architecture.md` (patterns)
-5. Acknowledge inherited context
+5. Read UX: `chati.dev/artifacts/4-UX/ux-specification.md` (Design System tokens, component states)
+6. Read Brandbook: `chati.dev/artifacts/4-UX/brandbook.md` (token values for visual comparison)
+7. Acknowledge inherited context
 
 **Agent-Driven Opening (brief status to user):**
 > "Dev has completed implementation. Running quality validation: tests, security scan, and code review..."
@@ -268,15 +270,54 @@ If the implementation includes a bug fix, verify causation:
 If not a bug fix, skip this phase and document: "Not a bug fix -- causation verification N/A."
 ```
 
+### Phase 5d: Visual Review (Mandatory for PRs touching UI files)
+
+CONDITION: Execute only when diff includes .tsx/.jsx/.vue/.svelte files or CSS/Tailwind changes.
+If no UI files changed: document "Phase 5d: N/A — no UI files changed."
+
+```
+1. Start dev server if not running (`npm run dev` or equivalent).
+
+2. For each page/route affected by the diff:
+
+   a. Desktop (1280px): browser_navigate → browser_take_screenshot
+   b. Tablet (768px): set viewport → navigate → screenshot
+   c. Mobile (375px): set viewport → navigate → screenshot
+
+3. Analyze each screenshot against:
+   - Brandbook token compliance (colors, spacing, typography)
+   - Component state completeness (hover, focus, error, loading)
+   - No visual regressions (broken layout, overflow, misalignment)
+   - Responsive correctness at all 3 viewports
+
+4. Classify findings:
+   - VISUAL-ERROR (blocks APPROVED): wrong brand colors, broken layout, missing states
+   - VISUAL-WARNING (noted, does not block): minor spacing, animation timing
+
+5. If VISUAL-ERROR found: send correction to Dev agent (Silent Correction Loop).
+
+6. Document in report:
+   ## Visual Review
+   | Route | Desktop | Tablet | Mobile | Tokens | Responsive | Status |
+   |-------|---------|--------|--------|--------|------------|--------|
+   | /{route} | {screenshot} | {screenshot} | {screenshot} | {PASS/FAIL} | {PASS/FAIL} | {OK/ERROR/WARNING} |
+
+FALLBACK: If browser MCP unavailable:
+  - Check Dev handoff for screenshot evidence (Step 9.7)
+  - If Dev provided screenshots: use those as visual evidence
+  - If no screenshots anywhere: flag VISUAL-WARNING "No visual evidence" and note in report
+```
+
 ### Phase 6: Score & Decide
 ```
 Calculate overall quality score:
-  Tests: weight 0.25
+  Tests: weight 0.20
   Coverage: weight 0.10
-  Security: weight 0.25
+  Security: weight 0.20
   Code Quality: weight 0.15
   Acceptance Criteria: weight 0.10
   Adversarial Review: weight 0.15
+  Visual Review: weight 0.10 (0.00 when no UI files — redistribute to Tests + Security)
 
 Result:
   - All checks pass AND adversarial review complete -> APPROVED -> proceed to DevOps

package/framework/config.yaml

@@ -1,8 +1,8 @@
 # chati.dev Configuration
-version: "4.1.4"
+version: "4.1.6"
 installed_at: "2026-02-07T10:00:00Z"
 updated_at: "2026-04-06T00:00:00Z"
-installer_version: "4.1.4"
+installer_version: "4.1.6"
 project_type: greenfield
 language: en
 ides: [claude-code]

package/framework/constitution.md

@@ -489,5 +489,5 @@ When multiple CLI providers are enabled, the system SHALL coordinate agent execu
 
 ---
 
-*Chati.dev Constitution v4.1.4 — 19 Articles + Preamble*
+*Chati.dev Constitution v4.1.6 — 19 Articles + Preamble*
 *All agents are bound by this Constitution. Violations are enforced per article.*

package/framework/context/root.md

@@ -1,7 +1,7 @@
 # Chati.dev System Context
 
 ## Framework
-- **Version**: 4.1.4
+- **Version**: 4.1.6
 - **Agents**: Specialized agents across DISCOVER, PLAN, BUILD, DEPLOY phases
 - **Constitution**: 19 Articles + Preamble
 - **Quality**: 5 pipeline gates + 3-tier verdicts (APPROVED / NEEDS_REVISION / BLOCKED)

package/framework/data/entity-registry.yaml

@@ -3,7 +3,7 @@
 # and by the Health Check for system integrity validation.
 
 metadata:
-  version: "4.1.4"
+  version: "4.1.6"
   last_updated: "2026-04-06T00:00:00Z"
   entity_count: 62
   checksum_algorithm: sha256

package/framework/hooks/style-guard.js

@@ -112,9 +112,10 @@ async function main() {
     }
 
     if (result.violations.length > 0) {
+      // Block all style violations — agent must rewrite
       process.stdout.write(JSON.stringify({
-        decision: 'allow',
-        reason: `[Style Guard] ${result.violations.join(' ')}`,
+        decision: 'block',
+        reason: `[Style Guard] ${result.violations.join(' ')} Rewrite without em-dashes and emojis.`,
       }));
       return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chati-dev",
-  "version": "4.1.4",
+  "version": "4.1.6",
   "description": "AI-Powered Multi-Agent Orchestration System — Structured vibe coding for Full Stack Development",
   "type": "module",
   "bin": {

package/src/config/gemini-hooks-generator.js

@@ -533,14 +533,14 @@ main();
 
 /**
  * Generate the style guard hook for Gemini CLI.
- * BeforeTool event -- advisory: enforces em-dash and emoji standards.
+ * BeforeTool event -- blocking: rejects em-dashes and emojis in generated content.
  */
 function generateStyleGuard() {
   return `${HOOK_HEADER}
 /**
  * Style Guard -- BeforeTool
- * Advisory: enforces Constitution Article V writing standards
- * (no em-dashes, no emojis in generated content).
+ * Blocking: rejects em-dashes and emojis in generated content.
+ * Constitution Article V enforcement.
  */
 async function main() {
   let input = '';
@@ -584,8 +584,8 @@ async function main() {
 
     if (result.violations && result.violations.length > 0) {
       console.log(JSON.stringify({
-        decision: 'allow',
-        reason: \`[Style Guard] \${result.violations.join(' ')}\`,
+        decision: 'block',
+        reason: \`[Style Guard] \${result.violations.join(' ')} Rewrite without em-dashes and emojis.\`,
       }));
       return;
     }

package/src/installer/core.js

@@ -148,7 +148,7 @@ export async function installFramework(config) {
 /**
  * Copy framework files from the Chati.dev source directory
  */
-function copyFrameworkFiles(destDir, provider = 'claude') {
+export function copyFrameworkFiles(destDir, provider = 'claude') {
   if (!existsSync(FRAMEWORK_SOURCE)) return;
 
   const filesToCopy = [

package/src/orchestrator/cli.js

@@ -914,8 +914,15 @@ async function handleScan(projectDir, args) {
         const { scanProjectSecurity } = await import('../scanning/security-scanner.js');
         return scanProjectSecurity(projectDir, { language: args.language, dir: args.dir });
       }
+      case 'ui': {
+        const file = args.file;
+        if (!file) return errorResult('Missing --file flag for UI scan', 'MISSING_FILE');
+        const { scanUIQuality } = await import('../scanning/ui-scanner.js');
+        const { join: joinPath } = await import('path');
+        return scanUIQuality(joinPath(projectDir, file));
+      }
       default:
-        return errorResult(`Unknown scan type: ${type}. Valid: placeholders, leakage, density, env, security`, 'UNKNOWN_SCAN_TYPE');
+        return errorResult(`Unknown scan type: ${type}. Valid: placeholders, leakage, density, env, security, ui`, 'UNKNOWN_SCAN_TYPE');
     }
   } catch (err) {
     return errorResult(`Scan failed: ${err.message}`, 'SCAN_ERROR');

package/src/orchestrator/handoff-engine.js

@@ -30,7 +30,7 @@ export function executeHandoff(projectDir, params) {
   const errors = [];
 
   // Validate preconditions
-  const preconditions = validateHandoffPreconditions(params);
+  const preconditions = validateHandoffPreconditions(params, projectDir);
   if (!preconditions.valid) {
     return {
       success: false,
@@ -113,7 +113,7 @@ export function executeHandoff(projectDir, params) {
  * @param {object} params
  * @returns {{ valid: boolean, issues: string[] }}
  */
-export function validateHandoffPreconditions(params) {
+export function validateHandoffPreconditions(params, projectDir = '.') {
   const issues = [];
 
   // Check validation exists and passed
@@ -148,6 +148,19 @@ export function validateHandoffPreconditions(params) {
     issues.push('Handoff summary is required');
   }
 
+  // Deterministic artifact checks for UX agent handoffs
+  const agent = params.fromTask?.agent || params.fromTask?.id?.split('-')[0] || '';
+  if (agent === 'ux') {
+    const brandbookPath = join(projectDir, 'chati.dev', 'artifacts', '4-UX', 'brandbook.html');
+    if (!existsSync(brandbookPath)) {
+      issues.push('brandbook.html is missing — UX handoff requires the visual brandbook file on disk');
+    }
+    const discoveryLogPath = join(projectDir, 'chati.dev', 'artifacts', '4-UX', 'component-discovery-log.md');
+    if (!existsSync(discoveryLogPath)) {
+      issues.push('component-discovery-log.md is missing — UX handoff requires component discovery documentation');
+    }
+  }
+
   return {
     valid: issues.length === 0,
     issues,
@@ -319,6 +332,20 @@ export function validateHandoffIntegrity(handoff, receivingAgent) {
     }
   }
 
+  // Check for screenshot evidence from Dev agent (UI tasks)
+  if (handoff.from_agent === 'dev' || handoff.agent === 'dev') {
+    const hasUIOutputs = handoff.outputs && handoff.outputs.some(o =>
+      /\.(tsx|jsx|vue|svelte|css)$/i.test(o)
+    );
+    if (hasUIOutputs) {
+      const hasVisualEvidence = handoff.summary &&
+        (handoff.summary.includes('Visual review PASSED') || handoff.summary.includes('screenshot'));
+      if (!hasVisualEvidence) {
+        warnings.push('Dev agent produced UI files but no visual review evidence found in handoff — manual visual review recommended');
+      }
+    }
+  }
+
   return {
     valid: missing.length === 0,
     missing,

package/src/scanning/index.js

@@ -5,3 +5,4 @@ export { scanImplementationLeakage, extractFRSection, TECH_NAMES } from './leaka
 export { scanInformationDensity, FILLER_PATTERNS } from './density-scanner.js';
 export { scanEnvSync, parseEnvFile, grepEnvUsage } from './env-scanner.js';
 export { scanProjectSecurity, detectLanguage } from './security-scanner.js';
+export { scanUIQuality, UI_QUALITY_CHECKS } from './ui-scanner.js';

package/src/scanning/ui-scanner.js

@@ -0,0 +1,120 @@
+/**
+ * UI Quality Scanner -- Detects hardcoded visual values in UI files.
+ * Deterministic regex scan. Zero LLM dependency.
+ *
+ * Catches common "vibecoded" patterns:
+ * - Hardcoded hex colors (should use design tokens)
+ * - Inline styles with px values (should use spacing tokens)
+ * - !important in CSS (code smell)
+ * - Images without alt attributes (accessibility)
+ * - Inline style= attributes (should use classes/tokens)
+ */
+
+import { readFileSync } from 'fs';
+
+/**
+ * UI quality patterns. Each has an id, pattern, severity, and description.
+ */
+export const UI_QUALITY_CHECKS = [
+  {
+    id: 'HARDCODED_HEX_COLOR',
+    pattern: /(?<![\\w-])(?:color|background|border|fill|stroke)\s*:\s*#[0-9a-fA-F]{3,8}\b/g,
+    severity: 'high',
+    description: 'Hardcoded hex color in CSS property — use design tokens instead',
+  },
+  {
+    id: 'INLINE_STYLE',
+    pattern: /\bstyle\s*=\s*["'{]/g,
+    severity: 'medium',
+    description: 'Inline style attribute — use CSS classes or design tokens',
+  },
+  {
+    id: 'CSS_IMPORTANT',
+    pattern: /!\s*important/gi,
+    severity: 'medium',
+    description: '!important in CSS — indicates specificity problem',
+  },
+  {
+    id: 'IMG_MISSING_ALT',
+    pattern: /<img(?![^>]*\balt\s*=)[^>]*>/gi,
+    severity: 'high',
+    description: 'Image tag without alt attribute — accessibility violation',
+  },
+  {
+    id: 'HARDCODED_PX_INLINE',
+    pattern: /style\s*=\s*["'][^"']*\d+px[^"']*["']/g,
+    severity: 'medium',
+    description: 'Hardcoded px values in inline style — use spacing tokens',
+  },
+  {
+    id: 'HARDCODED_RGBA',
+    pattern: /(?<![\\w-])(?:color|background|border|fill|stroke)\s*:\s*rgba?\([^)]+\)/g,
+    severity: 'high',
+    description: 'Hardcoded rgba color — use design tokens instead',
+  },
+];
+
+/**
+ * File extensions this scanner targets.
+ */
+const UI_FILE_EXTENSIONS = ['.tsx', '.jsx', '.vue', '.svelte', '.css', '.scss'];
+
+/**
+ * Paths to skip (config files, design token definitions, tailwind config).
+ */
+const SKIP_PATTERNS = [
+  /tailwind\.config/,
+  /globals\.css$/,
+  /tokens?\./,
+  /theme\./,
+  /\.config\./,
+  /node_modules/,
+  /brandbook/,
+];
+
+/**
+ * Check if a file should be scanned.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function shouldScan(filePath) {
+  const hasUIExtension = UI_FILE_EXTENSIONS.some(ext => filePath.endsWith(ext));
+  const isSkipped = SKIP_PATTERNS.some(p => p.test(filePath));
+  return hasUIExtension && !isSkipped;
+}
+
+/**
+ * Scan a file for UI quality violations.
+ * @param {string} filePath - Path to file to scan
+ * @returns {{ clean: boolean, findings: Array<{id: string, match: string, line: number, severity: string, description: string}>, count: number, skipped: boolean }}
+ */
+export function scanUIQuality(filePath) {
+  if (!shouldScan(filePath)) {
+    return { clean: true, findings: [], count: 0, skipped: true };
+  }
+
+  const content = readFileSync(filePath, 'utf-8');
+  const findings = [];
+
+  for (const check of UI_QUALITY_CHECKS) {
+    const re = new RegExp(check.pattern.source, check.pattern.flags);
+    let match;
+    while ((match = re.exec(content)) !== null) {
+      const line = content.slice(0, match.index).split('\n').length;
+      findings.push({
+        id: check.id,
+        match: match[0].slice(0, 80),
+        line,
+        severity: check.severity,
+        description: check.description,
+      });
+    }
+  }
+
+  return {
+    clean: findings.length === 0,
+    findings,
+    count: findings.length,
+    skipped: false,
+  };
+}