qualia-framework 4.4.0 → 5.1.0

package/hooks/vercel-account-guard.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/vercel-account-guard.js — block deploys from wrong Vercel account.
+//
+// PreToolUse hook on `Bash`. Reads the proposed command from the Claude Code
+// hook payload (stdin JSON: tool_input.command) and exits 2 to BLOCK, 0 to
+// allow. Triggers only when the command matches `vercel --prod` or `vercel deploy`.
+//
+// Allowed teams are read from ~/.claude/.vercel-allowed-teams (one slug per
+// line, mode 0600). Missing config file = fail-open with stderr warning.
+//
+// Cross-platform (Windows/macOS/Linux). No external dependencies.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawnSync } = require("child_process");
+
+const _traceStart = Date.now();
+
+function _trace(result, extra) {
+  try {
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: "vercel-account-guard",
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+// Read hook payload from stdin.
+let command = "";
+try {
+  if (!process.stdin.isTTY) {
+    const raw = fs.readFileSync(0, "utf8");
+    if (raw) command = (JSON.parse(raw).tool_input || {}).command || "";
+  }
+} catch {}
+
+if (!command) {
+  _trace("allow", { reason: "no-command" });
+  process.exit(0);
+}
+
+// Only act on vercel deploy commands.
+if (!/vercel\s+(--prod|deploy)/.test(command)) {
+  _trace("allow", { reason: "not-vercel-deploy" });
+  process.exit(0);
+}
+
+// Read allowed teams (one slug per line).
+const teamsFile = path.join(os.homedir(), ".claude", ".vercel-allowed-teams");
+let allowed;
+try {
+  allowed = fs.readFileSync(teamsFile, "utf8").split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+} catch {
+  allowed = [];
+}
+if (allowed.length === 0) {
+  console.error("No .vercel-allowed-teams configured -- skipping account check");
+  _trace("skipped", { reason: "no-config" });
+  process.exit(0);
+}
+
+// Run `vercel whoami` to get the active account (fail-open on error).
+const r = spawnSync("vercel", ["whoami"], {
+  encoding: "utf8", timeout: 5000, shell: process.platform === "win32",
+});
+const actual = ((r.status === 0 && !r.error) ? (r.stdout || "") : "").trim();
+if (!actual) {
+  console.error("vercel whoami failed or empty -- skipping account check");
+  _trace("skipped", { reason: "whoami-unavailable" });
+  process.exit(0);
+}
+
+if (allowed.includes(actual)) {
+  _trace("allow", { actual, allowed_count: allowed.length });
+  process.exit(0);
+}
+
+// Block: wrong account.
+const msg = `BLOCKED: Wrong Vercel account/team. Active: '${actual}'. Allowed: ${allowed.join(", ")}. Run \`vercel switch ${allowed[0]}\` first, or add this team to ~/.claude/.vercel-allowed-teams.`;
+console.error(msg);
+console.log(msg);
+_trace("block", { actual, allowed_count: allowed.length, reason: "wrong-account" });
+process.exit(2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "4.4.0",
+  "version": "5.1.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -42,6 +42,7 @@
     "tests/",
     "docs/",
     "CLAUDE.md",
+    "AGENTS.md",
     "guide.md"
   ],
   "engines": {

package/rules/design-brand.md

@@ -0,0 +1,114 @@
+---
+globs: ["*.tsx", "*.jsx", "*.css", "*.scss", "*.html", "*.vue", "*.svelte"]
+---
+
+# Design — Brand register
+
+**When this register applies:** marketing pages, landing pages, campaign sites, portfolios, brand microsites, anything where the design IS the product.
+
+**The bar:** distinctiveness. Memorable beats safe. If a visitor can't remember what your site looked like an hour later, you failed.
+
+This register inherits all of `design-laws.md`. The rules below add what changes when distinctiveness, not familiarity, is the goal.
+
+## The brand brief (what the agent commits to first)
+
+Before any code, the agent writes a 4-line brief and waits for user confirmation:
+
+```
+Aesthetic direction:  [editorial · brutalist · luxury · maximalist · retro-futuristic · organic · terminal-native · sci-fi · pastoral · industrial · ...]
+Color strategy:       [Restrained · Committed · Full palette · Drenched]
+Scene sentence:       [single concrete sentence — who, where, ambient light, mood]
+Differentiation:      [what someone will remember 24 hours later]
+```
+
+This is mandatory. Skipping it produces generic output that ignores the brand.
+
+## Reflex-reject aesthetic lanes
+
+The currently-saturated AI-design families. Reject by default unless the user explicitly asks for one and you confirmed they understand it's a saturated lane.
+
+| Lane | Tells | Reject because |
+|---|---|---|
+| **Generic SaaS-cream** | Off-white bg, soft shadows, rounded cards, slate text, one-color accent | Notion clone aesthetic. Every AI tool builds this first |
+| **Vercel-terminal-native** | Dark + monospace + green/blue accents + grain | The 2024-2025 v0 aesthetic. Saturated |
+| **Crypto-neon** | Pure black + electric accent + glow + grid | Web3 cliché |
+| **Healthcare-clinical** | White + teal + rounded sans + soft icons | Every health app |
+| **Fintech-navy-gold** | Navy + gold accent + serif headings | Every bank, every wealth tool |
+| **Sleek-corporate** | Inter + blue + gradient mesh + isometric illustrations | Every B2B SaaS landing 2020-2024 |
+
+If the project lands in one of these by default, the slop test failed at second-order. Rework.
+
+## Brand register — additional laws
+
+### Typography
+
+- Pick a **distinctive display face**. Editorial serifs (Fraunces, Reckless, Ogg, Editorial New, Mazius). Geometric grotesques (Migra, Söhne, Gambarino). Variable display fonts (Authentic Sans, Departure Mono).
+- Pair the display with a **refined body**. JetBrains Mono, Geist, Inter Display (NOT Inter), Söhne, Untitled Sans, Mona Sans, Switzer.
+- **Banned display fonts:** Inter, Roboto, Arial, system-ui, Space Grotesk, Montserrat, Poppins, Lato, Open Sans. These are the AI defaults — and the worst signal of "designer didn't choose this."
+- **Variable fonts encouraged.** A single variable font with axis-driven weight/optical-size is more interesting than three static cuts.
+
+### Color
+
+- Brand register defaults to **Committed** color strategy. One saturated color carries identity.
+- **Drenched** is a strong choice for hero sections. Don't be afraid.
+- Accent should be **sharp** — not a desaturated pastel-of-the-brand. The accent is the loudest element on the page.
+
+### Layout
+
+- **Asymmetry > symmetry.** Real design has tension. Centered-everything is the AI default.
+- **Diagonal flow, overlap, grid-breaking elements** when they serve the design.
+- **Scale contrast.** Hero text at clamp(4rem, 9vw, 8rem) next to body at 1rem creates drama. Hero at 2.5rem next to body at 1rem is timid.
+- **Negative space is content.** Generous whitespace > dense layouts for marketing.
+
+### Motion
+
+- One **signature motion** that gives the site personality:
+  - Parallax scroll-triggered reveal
+  - Magnetic buttons
+  - Cursor-following element
+  - Letter-by-letter text reveal on hero
+  - Scroll-driven scrubbed scene
+  - Morphing shapes between sections
+- Subtle elsewhere. Restraint everywhere except the signature.
+- Use the Web Animations API or Framer Motion for orchestrated sequences. CSS keyframes for one-offs.
+
+### Backgrounds and visual details
+
+This is where Brand earns its register. Allowed and encouraged:
+
+- Gradient meshes (CSS or SVG)
+- Noise textures (subtle, 2-5% opacity)
+- Geometric patterns (SVG, not images)
+- Layered transparencies
+- Dramatic shadows (with brand-tinted color, not gray)
+- Decorative borders (sparingly)
+- Custom cursors (page-specific, not site-wide)
+- Grain overlays on images
+- Scroll-progress indicators (interesting ones, not generic top bars)
+
+Don't use all of these on one page. Pick 1-2 that serve the brief.
+
+## Brand-specific anti-patterns
+
+In addition to `design-laws.md` absolute bans:
+
+- **Hero pattern: text-center + gradient bg + 2 CTAs + screenshot below.** The single most overused brand pattern of 2020-2025.
+- **Three-column feature grid in section 2.** The default AI brand layout.
+- **"Trusted by" logo strip in faded gray.** Lazy social proof. If the logos matter, design with them. If they don't, omit.
+- **Parallax scroll on every section.** Heavy-handed. Use it for the signature, nowhere else.
+- **Animated dots / pulsing orbs / blinking status indicators.** Decorative noise.
+- **Generic "Get Started" / "Learn More" CTA pair.** Always specify the action.
+- **Stock photography of diverse smiling people in offices.** Use illustration, abstract imagery, product screenshots, or no imagery at all.
+
+## Brand register success criteria
+
+If you can answer YES to all of these, the brand register passed:
+
+- [ ] A designer would call this **distinctive** — not "polished" but **specific**
+- [ ] The aesthetic direction is identifiable in 3 seconds
+- [ ] The color strategy is one of the four (and reads that way)
+- [ ] The scene sentence and the page agree
+- [ ] One signature motion, executed well
+- [ ] No reflex-reject lane (first or second order)
+- [ ] All anti-references avoided
+- [ ] Implementation matches vision (effort proportional to ambition)

package/rules/design-laws.md

@@ -0,0 +1,148 @@
+---
+globs: ["*.tsx", "*.jsx", "*.css", "*.scss", "*.html", "*.vue", "*.svelte"]
+---
+
+# Design Laws
+
+The non-negotiable rules every Qualia frontend honors. Both registers (Brand and Product) inherit from this file. Skip nothing.
+
+These laws exist because AI-generated UI has identifiable defaults — Inter font, purple gradients, identical card grids, gray-on-gray, modal-as-first-thought — and shipping the defaults is shipping AI slop. Each rule below has a specific failure mode it prevents.
+
+## 1. Color: OKLCH only
+
+Use the OKLCH color space for every color in the codebase. RGB / hex / HSL are translated values, not source values.
+
+```css
+/* yes */
+--bg:     oklch(0.16 0.012 220);
+--accent: oklch(0.78 0.14 196);
+
+/* no */
+--bg:     #1a1d22;
+--accent: #00ced1;
+```
+
+**Why:** OKLCH is perceptually uniform. Equal lightness numbers look equally light to the eye, regardless of hue. Hex doesn't give you that — `#777777` and `#7777ff` are nominally equal lightness but the blue reads darker.
+
+**Reduce chroma at the extremes.** As lightness approaches 0 or 100, high chroma reads garish. Cap chroma at 0.04 below L=0.20 and above L=0.92.
+
+**Never use `#000` or `#fff`.** Tint every neutral toward the brand hue with chroma 0.005–0.01. Pure black/white reads as untuned and generic — the dead giveaway of "designer didn't pick this color, the framework did."
+
+```css
+/* tinted neutrals */
+--text:  oklch(0.94 0.006 220);   /* 220 is the brand hue */
+--bg:    oklch(0.16 0.012 220);
+--muted: oklch(0.62 0.010 220);
+```
+
+## 2. Color strategy: pick one, commit to it
+
+Before picking colors, pick a strategy. Four steps on a commitment axis:
+
+| Strategy | Rule | When |
+|---|---|---|
+| **Restrained** | Tinted neutrals + one accent at ≤10% surface coverage | Product default; brand minimalism |
+| **Committed** | One saturated color carries 30–60% of the surface | Brand default for identity-driven pages |
+| **Full palette** | 3–4 named roles, each used deliberately | Brand campaigns; product data viz |
+| **Drenched** | The surface IS the color | Brand heroes; campaign pages |
+
+The "≤10% accent" rule is **Restrained only**. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex.
+
+## 3. Theme: write a scene sentence
+
+Dark vs light is never a default. Not dark "because tools look cool dark." Not light "to be safe." Before choosing, write **one sentence of physical scene**: who uses this, where, under what ambient light, in what mood.
+
+| Vague (no answer) | Concrete (forces an answer) |
+|---|---|
+| "Observability dashboard" | "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" |
+| "Customer support tool" | "Agent at a coffee-lit desk juggling 4 chats while a coworker asks a question" |
+| "Marketing site" | "Founder showing the page to an investor on an iPad in a sunlit lobby" |
+
+Run the sentence, not the category. If the sentence doesn't force an answer, add detail until it does.
+
+## 4. Typography
+
+- Body line length capped at 65–75ch
+- Hierarchy through scale + weight contrast (≥1.25 ratio between adjacent steps)
+- Avoid flat scales — if h1 is 32px and h2 is 28px, the hierarchy is invisible
+- Letter-spacing as a semantic signal:
+  - Display headlines: tight (-0.02em to -0.04em)
+  - Body: neutral (0)
+  - Labels and badges: open (+0.04em to +0.08em)
+  - Category tags: wide (+0.08em to +0.14em)
+
+## 5. Layout
+
+- **Vary spacing for rhythm.** Same padding everywhere is monotony. Tight within groups, generous between sections.
+- **Cards are the lazy answer.** Use them only when they're truly the best affordance. Nested cards are always wrong.
+- **Container depth max 2.** Card → content. Not card → panel → pill → content.
+- **Don't wrap everything in a container.** Most things don't need one.
+- **Full-width with fluid padding.** No hardcoded `max-width: 1200px` or `max-w-7xl`. Use `clamp(1rem, 5vw, 4rem)` for horizontal padding.
+
+## 6. Motion
+
+- Don't animate CSS layout properties (`width`, `height`, `top`, `left`, `margin`, `padding`). Animate `transform` and `opacity`.
+- Ease out with exponential curves: `cubic-bezier(0.22, 1, 0.36, 1)` (out-quart) or `cubic-bezier(0.16, 1, 0.3, 1)` (out-expo). No bounce. No elastic.
+- One signature motion per page > scattered micro-interactions
+- Always respect `prefers-reduced-motion: reduce`
+
+## 7. Copy
+
+- Every word earns its place
+- No restated headings
+- No intros that repeat the title
+- **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`.
+- CTAs name the action. "Download invoice" not "Get Started". "Continue setup" not "Learn More".
+
+## 8. Absolute bans (match-and-refuse)
+
+If you're about to write any of these, rewrite the element with different structure. No exceptions.
+
+| Banned pattern | Why | Rewrite with |
+|---|---|---|
+| **Side-stripe borders** — `border-left: 4px` colored as accent on cards / list items / callouts | Decorative noise, never semantic | Full borders, background tints, leading numbers/icons, or nothing |
+| **Gradient text** — `background-clip: text` with a gradient | Decorative, never meaningful | Single solid color. Emphasis via weight or size |
+| **Glassmorphism by default** — blur + glass cards used everywhere | Trendy slop from 2023-2024 | Rare and purposeful, or nothing |
+| **Hero-metric template** — big number, small label, three supporting stats, gradient accent | SaaS cliché | Vary layout per metric. Don't grid them |
+| **Identical card grids** — same-sized cards with icon + heading + text repeated 3+ times | The default AI hero pattern | Vary card sizes, layouts, content shapes |
+| **Modal as first thought** — every action goes through a modal | Lazy interaction design | Inline expansion, progressive disclosure, dedicated route |
+
+## 9. The AI slop test (run at two altitudes)
+
+If someone could look at this interface and say "AI made that" without doubt, it failed.
+
+**First-order check.** If someone could guess the theme + palette from the category alone, the first reflex won:
+- Observability → dark blue
+- Healthcare → white + teal
+- Finance → navy + gold
+- Crypto → neon on black
+
+If yes, rework the scene sentence and color strategy until the answer isn't obvious from the domain.
+
+**Second-order check.** If someone could guess the aesthetic family from category-plus-anti-references, the trap one tier deeper won:
+- AI workflow tool that's not SaaS-cream → editorial-typographic
+- Fintech that's not navy-and-gold → terminal-native dark mode
+- Health app that's not white-and-teal → soft-pastel
+
+The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The Brand register's reflex-reject aesthetic lanes catch the currently-saturated families.
+
+## 10. Single-icon-family rule
+
+Pick one icon family per project and enforce it. Lucide OR Heroicons OR Phosphor OR Radix Icons. Never mixed. Mixing icon families is the visual equivalent of mixing fonts.
+
+## 11. Anti-references are mandatory
+
+Every PRODUCT.md must list 3–5 sites the project should NOT look like. Anti-references are more useful than positive references because they pin down what the design is reacting against.
+
+```
+Anti-references:
+- generic SaaS-cream (Notion clones)
+- terminal-nostalgia (vercel/v0 dark)
+- corporate-navy fintech (most banks)
+```
+
+## 12. The implementation must match the vision
+
+Maximalist designs need elaborate code. Minimalist designs need restraint, precision, and careful attention to spacing and typography. The failure mode is mismatch: elaborate animation on a "clean minimal" claim, or flat execution of an ambitious concept.
+
+If you wrote 200 lines of CSS to render a "minimal" landing page, the page is not minimal. If your "bold and maximalist" page uses 4 colors and `text-center`, it's not bold.

package/rules/design-product.md

@@ -0,0 +1,114 @@
+---
+globs: ["*.tsx", "*.jsx", "*.css", "*.scss", "*.html", "*.vue", "*.svelte"]
+---
+
+# Design — Product register
+
+**When this register applies:** app UI, admin consoles, dashboards, internal tools, settings pages, anything where the design SERVES the product.
+
+**The bar:** earned familiarity. Fluent users of Linear, Figma, Notion, Stripe, Raycast should trust the interface on first glance. Distinctiveness is allowed but never at the cost of usability.
+
+This register inherits all of `design-laws.md`. The rules below add what changes when familiarity, not distinctiveness, is the goal.
+
+## The product brief (what the agent commits to first)
+
+Before any code, the agent writes a 4-line brief and waits for user confirmation:
+
+```
+Reference apps:       [Linear · Stripe · Notion · Figma · Raycast · Vercel · Plaid Dashboard · Pylon · ...]
+Color strategy:       [Restrained — almost always]
+Scene sentence:       [physical scene — focus on context of use, not aesthetic mood]
+Density:              [comfortable · standard · compact · ultra-compact]
+```
+
+Reference apps anchor the visual language. Pick 2-3 that share the user mental model and the density.
+
+## Density target
+
+Product UIs have to choose density. State it explicitly.
+
+| Density | Examples | Use when |
+|---|---|---|
+| **Comfortable** | Notion, Linear (default), Mailchimp | Knowledge work, low-frequency |
+| **Standard** | Stripe Dashboard, Vercel | Mainstream SaaS |
+| **Compact** | Linear (compact mode), Figma left rail | Power users, workflow tools |
+| **Ultra-compact** | Bloomberg Terminal, Trader UIs | Information-dense, professional users |
+
+Higher density = smaller font sizes (down to 12px), tighter padding, more rows per viewport. Don't pretend the app is comfortable when it's compact, or vice versa. Match the user's actual workflow.
+
+## Product register — additional laws
+
+### Typography
+
+- **One typeface family is fine** for product. Variable fonts shine here (Inter Display, Geist, Switzer, Mona Sans, Söhne, Untitled Sans).
+- Banned (per laws): Inter (regular cut), Roboto, Arial, system-ui, Space Grotesk
+- Body: 13-15px depending on density (comfortable=15, standard=14, compact=13, ultra-compact=12)
+- Hierarchy through weight (400 body, 500 labels, 600 headings) more than size
+- Tabular numerals for any numeric data: `font-feature-settings: "tnum" 1`
+- Truncate long strings with ellipsis + tooltip — never let layout collapse on a long username
+
+### Color
+
+- **Restrained is the default.** Tinted neutrals + one accent.
+- **Semantic colors required:** success (green) / warning (amber) / error (red) / info (blue). Always paired with non-color signal (icon, label, pattern).
+- Status indicators must work for color-blind users. Run the design through a deuteranopia simulator.
+- Background depth: 3 surface levels max (`bg`, `surface`, `elevated`). Subtle differences (oklch L delta of 0.03-0.05).
+
+### Layout
+
+- **Density first, aesthetics second.** A beautiful UI a user can't navigate quickly is a failed product UI.
+- **Predictable layout.** Sidebar left, main center, optional right rail. Don't reinvent navigation patterns.
+- **Sticky headers** for long-scroll views (tables, lists)
+- **Keyboard-first.** Every action accessible via keyboard. Power users will memorize shortcuts; expose them.
+- **Fitts's Law.** Frequently-used controls go to screen edges. Action buttons in tight clusters.
+
+### Components
+
+| Pattern | Product register rule |
+|---|---|
+| **Buttons** | 3 variants max: primary / secondary / ghost. Destructive variant where needed. No "outline + filled + ghost + soft + subtle" proliferation. |
+| **Inputs** | Always have visible labels (not placeholder-only). Validation inline, on blur. Error messages specific and actionable. |
+| **Tables** | Tabular numerals. Right-align numbers. Sort indicators on hover, persistent on active. Sticky headers. |
+| **Empty states** | Always include: icon, single sentence of context, primary action |
+| **Loading** | Skeleton (not spinner) for known-shape content. Spinner only for unknown duration. |
+| **Empty data** | Never "No results." Always "No invoices yet — try [action]." |
+| **Toasts** | Auto-dismiss at 5s minimum. Always dismissible. Errors don't auto-dismiss. |
+| **Modals** | Last resort (per laws). When unavoidable: trap focus, ESC to close, restore focus on close. |
+
+### Motion
+
+- Restrained. Product UI motion exists to communicate state changes, not to delight.
+- Hover transitions: 100-150ms ease-out
+- Panel slides: 200ms ease-out
+- Page transitions: 0ms (yes, zero) for navigation between similar views. Motion when it would disorient should be skipped.
+- Skeleton shimmer: 1500ms loop, subtle
+- No bounce. No elastic. No overshoot.
+
+### States (every interactive element)
+
+- Default
+- Hover (within 100ms)
+- Focus (visible ring, 2px+ offset, contrasting color)
+- Active/pressed (subtle scale or color shift)
+- Disabled (opacity 0.5, `cursor: not-allowed`, `aria-disabled="true"`)
+- Loading (per-element spinner or skeleton)
+- Error (inline message + `aria-describedby`)
+
+Every state on every interactive element. No exceptions.
+
+## Product register success criteria
+
+If you can answer YES to all of these, the product register passed:
+
+- [ ] A user fluent in the reference apps would feel oriented in 5 seconds
+- [ ] Density is consistent across the app (one chosen value, applied)
+- [ ] Keyboard navigation reaches every action
+- [ ] Empty / loading / error states present on every async surface
+- [ ] Color is never the sole information signal
+- [ ] Tabular numerals on numeric columns
+- [ ] No reinvented navigation pattern
+- [ ] Implementation matches vision (precision and restraint, not flourish)
+
+## When in doubt
+
+Ask: "Would Linear ship this?" If the answer is no, rework. Linear is not the only standard, but it is the highest commonly-cited bar for product design in 2025-2026 — fluency, restraint, density, motion all dialed in. Most product work will land within ±10% of Linear's bar; be honest about which side.

package/rules/design-rubric.md

@@ -0,0 +1,157 @@
+---
+globs: ["*.tsx", "*.jsx", "*.css", "*.scss", "*.html", "*.vue", "*.svelte"]
+---
+
+# Design Rubric
+
+Anchored 1-5 scoring across 8 dimensions. Used by the verifier agent to score frontend phases. Used by `/qualia-polish --critique` for read-only audits.
+
+## How to score
+
+Every dimension is scored 1-5 with EVIDENCE on the next line. Score without evidence is rejected.
+
+Anchored definitions:
+- **1** — Fails. Hard violation. WCAG fails, broken layout, absolute-ban hit.
+- **2** — Below acceptable. Functions but signals "AI generated this."
+- **3** — Acceptable. Ships. Not memorable, not embarrassing.
+- **4** — Good. Specific choices visible. A designer would approve.
+- **5** — Excellent. Distinctive. Worth screenshotting and sharing.
+
+**Default to 3.** Only score above 3 if you can cite a specific design principle the work excels at. Only score below 3 if you can quote evidence of a violation.
+
+If a vision model is critiquing screenshots, it must score against this rubric. Without anchoring, vision models say "looks great!" to everything.
+
+## Scope guard
+
+Score only what is scope-relevant. A `/qualia-polish src/components/Button.tsx` review scores Typography, Color, States, Motion, Microcopy. Skip Layout Originality and Container Depth — they're component-internal concerns at most.
+
+A whole-app `/qualia-polish` scores all 8 dimensions across multiple representative routes.
+
+## The 8 dimensions
+
+### 1. Typography
+
+| Score | Criteria |
+|---|---|
+| 1 | Inter / Roboto / Arial / system-ui / Space Grotesk as primary. Or single weight throughout. |
+| 2 | Project font loaded but only one weight, no scale, no letter-spacing variation. |
+| 3 | Project font with 2-3 weights, basic scale (h1/h2/body), readable. |
+| 4 | Distinctive display + refined body pair. Letter-spacing varied semantically (tight headlines, open labels). Tabular numerals on numeric data. |
+| 5 | Variable font with axis-driven weight/optical-size. Hierarchy through weight + scale + letter-spacing combined. Line lengths capped at 65-75ch. |
+
+Evidence format: `font-family: "<name>" used at line N, scale 14/16/24/40 visible, weights 400/500/700`
+
+### 2. Color cohesion
+
+| Score | Criteria |
+|---|---|
+| 1 | Hex values scattered in JSX. No CSS variables. Pure `#000` or `#fff`. |
+| 2 | CSS variables defined but unused (raw hex still appears). RGB used. |
+| 3 | All colors as CSS variables. Tinted neutrals (no pure black/white). One color strategy implied. |
+| 4 | OKLCH throughout. Strategy explicit (Restrained / Committed / Full / Drenched). WCAG AA verified. |
+| 5 | OKLCH with documented strategy. Chroma reduced at extremes. Brand-tinted shadows. APCA contrast verified for dense text. |
+
+Evidence: count of CSS custom properties for color, presence of OKLCH, evidence of strategy commitment
+
+### 3. Spatial rhythm
+
+| Score | Criteria |
+|---|---|
+| 1 | Arbitrary px values everywhere. No system. |
+| 2 | 8px grid roughly followed. Same padding everywhere. |
+| 3 | 8px grid consistently. Tight within groups, generous between sections. |
+| 4 | Fluid `clamp()` padding. Spacing varies by content type. Vertical rhythm identifiable. |
+| 5 | Spatial system reads as composed — different spacing for different relationships. Generous negative space. Asymmetry where intentional. |
+
+Evidence: presence of spacing tokens, padding values divisible by 4, `clamp()` usage
+
+### 4. Layout originality
+
+| Score | Criteria |
+|---|---|
+| 1 | Three-column feature grid in section 2. Card grid of 3 identical items. Centered hero with gradient. |
+| 2 | Standard hero + sections + footer. Symmetric throughout. |
+| 3 | Some layout variation across sections. No card monotony. |
+| 4 | Asymmetry, full-bleed, varied component sizes within a section. Negative space used. |
+| 5 | Layout reads as composed by a designer. Diagonal flow, overlap, scale contrast. Each section a different shape. |
+
+Evidence: file:line references showing layout choices
+
+### 5. Shadow & depth hierarchy
+
+| Score | Criteria |
+|---|---|
+| 1 | Single shadow value applied to everything (or no shadows). Nested cards. |
+| 2 | 2 shadow levels but applied inconsistently. |
+| 3 | 3 elevation levels (subtle / medium / pronounced). Brand-tinted, not pure gray. |
+| 4 | Shadows match elevation semantically. Different shadow for hover than rest. |
+| 5 | Multi-layer shadows (offset + ambient + directional). Brand-hue tinted at chroma 0.02-0.04. Spatial logic clear. |
+
+Evidence: count of distinct `box-shadow` values, OKLCH chroma in shadow color
+
+### 6. Motion intent
+
+| Score | Criteria |
+|---|---|
+| 1 | No transitions. Or: bounce/elastic everywhere. Animates layout properties. |
+| 2 | Default browser transitions on hover. No stagger. |
+| 3 | Considered transitions on interactive elements. Respects `prefers-reduced-motion`. |
+| 4 | One signature motion identified and executed. Stagger on entrance. Easing curves chosen (ease-out-quart or expo). |
+| 5 | Orchestrated motion that communicates structure. Scroll-driven if appropriate. Restraint elsewhere. |
+
+Evidence: easing curves used, presence of `prefers-reduced-motion`, file:line of signature motion
+
+### 7. Microcopy specificity
+
+| Score | Criteria |
+|---|---|
+| 1 | "Get Started" / "Learn More" / "Welcome to <product>" / "Click here". Lorem ipsum. |
+| 2 | Generic but functional ("Save", "Cancel", "Submit"). Empty states say "No results." |
+| 3 | Action-named CTAs ("Download invoice"). Empty states with one-sentence context. |
+| 4 | Voice consistent with brand. Errors specific and actionable ("This file is 12MB; max is 10MB. Compress and retry."). |
+| 5 | Microcopy you'd quote. Voice unmistakable. Every word earned. |
+
+Evidence: grep for banned phrases, sample of empty/error states
+
+### 8. Container depth & nesting
+
+| Score | Criteria |
+|---|---|
+| 1 | Card → panel → pill → content (depth ≥ 4). Side-stripe borders. Gradient text. |
+| 2 | Card-on-card pattern (depth 3). Most things wrapped in containers. |
+| 3 | Container depth ≤ 2. No decorative side-stripes. |
+| 4 | Containers used semantically only. Things that don't need a container don't have one. |
+| 5 | Layout reads as elements arranged on a surface, not boxes inside boxes. |
+
+Evidence: max DOM nesting depth on cards/panels, grep for `border-left` decorative usage
+
+## Aggregate score
+
+```
+total       = sum of dimension scores (max 40)
+average     = total / count_of_scored_dimensions
+phase_pass  = ALL scored dimensions ≥ 3
+phase_fail  = ANY scored dimension < 3
+```
+
+A phase fails if any dimension is below 3. Same gate as functional verification.
+
+## Output format (verifier agent contract)
+
+```markdown
+## Design Rubric — Phase {N}
+
+| Dim | Score | Evidence |
+|---|---|---|
+| Typography | 4 | `app/page.tsx:14` Fraunces + JetBrains Mono pair, weights 400/500/700, clamp() scale visible |
+| Color cohesion | 3 | All CSS vars in `app/globals.css:8-22`. OKLCH used. Strategy: Restrained. WCAG AA verified |
+| Spatial rhythm | 5 | Fluid clamp padding throughout, varied within section, generous between |
+| Layout originality | 2 | `app/page.tsx:42-78` is a three-column feature grid in section 2 — first-order slop. Rework. |
+| ... | ... | ... |
+
+**Aggregate:** 28/40 (avg 3.5)
+**Phase verdict:** FAIL — Layout Originality at 2 blocks the phase.
+**Fix priority:** Rework section 2. Replace three-column grid with varied-height layout per `design-brand.md` §Layout.
+```
+
+If the score < 3, the verifier writes the diagnosis. The fix is the next builder's task.

package/rules/grounding.md

@@ -1,3 +1,7 @@
+---
+globs: ["agents/**", "skills/**"]
+---
+
 # Grounding Protocol & Rubrics
 
 Shared quality standards for every Qualia skill and subagent. Reference from every SKILL.md and agent prompt that produces findings, scores, or recommendations.