qualia-framework 4.4.0 → 4.5.0

package/CLAUDE.md

@@ -36,8 +36,20 @@ For each milestone, for each phase:
      ↓
 /qualia-milestone  → close milestone, archive artifacts, prep next (human gate)
      ↓ (repeat for each milestone until Handoff)
+Design as a thread (v4.5.0+): every road agent loads PRODUCT.md +
+DESIGN.md + design-laws.md substrate. Builders run slop-detect on every
+frontend commit. Verifiers score 8 design dimensions per phase.
+
+/qualia-polish is now a flexible verb usable at any scope:
+  /qualia-polish src/components/Button.tsx     ~30s component touch-up
+  /qualia-polish app/dashboard                 ~3m  section pass
+  /qualia-polish                               ~12m whole app, fan-out
+  /qualia-polish --redesign                    ~30m ground-up redesign
+  /qualia-polish --critique                    read-only scored audit
+  /qualia-polish --quick                       ~1m  gates only
+
 Final milestone = Handoff:
-  /qualia-polish   → design/UX pass (Phase 1 of Handoff)
+  /qualia-polish   → final design pass (whole app)
   (content + SEO)  → Phase 2
   (final QA)       → Phase 3
   /qualia-ship     → deploy to production (quality gates → deploy → verify)

package/README.md

@@ -40,7 +40,7 @@ Open Claude Code in any project directory.
 ...repeat plan/build/verify per phase...
 /qualia-milestone   # Close current milestone, open next (loads next scope from JOURNEY.md)
 ...repeat per milestone until the final "Handoff" milestone...
-/qualia-polish      # Design and UX pass (first phase of the Handoff milestone)
+/qualia-polish      # Design pass — flexible scope: component, route, app, redesign, critique, quick
 /qualia-ship        # Deploy to production
 /qualia-handoff     # Enforce the 4 mandatory handoff deliverables
 /qualia-report      # Mandatory end-of-session report + ERP upload
@@ -77,7 +77,6 @@ Two human gates per project. One halt case (gap-cycle limit exceeded on a failin
 
 ```
 /qualia-debug     # Structured debugging
-/qualia-design    # One-shot design transformation
 /qualia-review    # Production audit (scored diagnostics)
 /qualia-optimize  # Deep optimization pass (parallel specialist agents)
 /qualia-quick     # Fast path for trivial fixes (skips planning)

package/agents/builder.md

@@ -84,10 +84,11 @@ Before committing:
 1. Run every command in **Validation:** — they must pass
 2. Mentally walk through each **Acceptance Criterion** — does the code actually produce that observable behavior?
 3. Run `npx tsc --noEmit` if you touched TypeScript files
-4. No `// TODO`, no placeholder text, no stub functions
-5. Imports are wired — not just declared but actually used
+4. **If you touched any `.tsx/.jsx/.css/.scss/.html` file: run `node bin/slop-detect.mjs {touched paths}`. Exit 1 (critical findings) BLOCKS the commit.** Fix the findings (apply the rewrite recipe in the script's output), re-run, repeat until exit 0.
+5. No `// TODO`, no placeholder text, no stub functions
+6. Imports are wired — not just declared but actually used
 
-If any Validation command fails or any AC is not met, fix before committing. Do not commit and hope the verifier catches it.
+If any Validation command fails, slop-detect returns 1, or any AC is not met, fix before committing. Do not commit and hope the verifier catches it.
 
 ### 5. Commit
 One atomic commit per task:
@@ -132,23 +133,14 @@ Rule of thumb: If you can explain the change in one sentence in a commit message
    - Always check auth server-side
    - Enable RLS on every table
    - Validate input with Zod at system boundaries
-5. **Frontend standards (mandatory for any .tsx/.jsx/.css file):**
-   - Before writing any frontend code: read `.planning/DESIGN.md` if it exists — it's the design source of truth
-   - If no DESIGN.md, apply rules from `rules/frontend.md` (Qualia defaults)
-   - Distinctive fonts (never Inter, Roboto, Arial, system-ui, Space Grotesk)
-   - Cohesive color palette via CSS variables — sharp accent for CTAs
-   - All text: WCAG AA contrast (4.5:1 normal, 3:1 large text)
-   - Full-width fluid layouts — no hardcoded max-width caps
-   - Every interactive element needs ALL states: hover, focus (visible ring), active, disabled, loading, error, empty
-   - Semantic HTML (`nav`, `main`, `section`, `article`) — not div soup
-   - Keyboard accessible: Tab, Enter, Escape, Arrow keys work
-   - Touch targets: 44px minimum
-   - Form inputs: visible labels (not placeholder-only), error messages with `aria-describedby`
-   - Motion: 150–200ms hover, 250ms expand, stagger children on load, respect `prefers-reduced-motion`
-   - Mobile-first responsive: stack on mobile, expand on desktop, fluid typography
-   - Skip link on every page, heading hierarchy (one h1, sequential order)
-   - No emoji as icons — use SVGs
-   - `cursor: pointer` on all clickable elements
+5. **Frontend standards (mandatory for any .tsx/.jsx/.css/.scss/.html file):**
+   - **Read substrate first.** Before any frontend code: read `PRODUCT.md`, `DESIGN.md`, `rules/design-laws.md`, AND the matching register file (`rules/design-brand.md` if `register: brand`, `rules/design-product.md` if `register: product`). These ARE the source of truth.
+   - **Honor the task's `**Design:**` contract.** If the planner specified `Tokens used: var(--accent), --space-4`, those are the tokens you use — don't introduce new ones without flagging.
+   - **OKLCH only.** No `#000`, no `#fff`, no scattered hex. Reference design tokens via `var(--name)`.
+   - **Banned fonts:** Inter, Roboto, Arial, Helvetica, system-ui, Space Grotesk. Use the font defined in DESIGN.md §3.
+   - **No purple-blue gradients, no gradient text, no side-stripe borders, no glassmorphism by default, no identical card grids, no modal as first thought, no em dashes** (per `rules/design-laws.md` §8 absolute bans).
+   - **Pre-commit guard:** run `node bin/slop-detect.mjs {touched files}`. Exit 1 = blocked.
+   - All other rules (states, semantics, keyboard, touch targets, motion, responsive, headings, skip links, no-emoji-icons, cursor:pointer, WCAG AA) carry over from `rules/design-laws.md` and the register file.
 6. **No empty catch blocks.** At minimum, log the error.
 7. **No dangerouslySetInnerHTML.** No eval().
 8. **React/Next.js performance:**

package/agents/plan-checker.md

@@ -105,6 +105,24 @@ If `.planning/phase-{N}-context.md` exists, read its "Locked Decisions" section.
 
 **FAIL if:** plan contradicts a locked decision (e.g., context says "use library X" but plan uses library Y).
 
+### Rule 7b: Frontend tasks have a design contract (v4.5.0+)
+
+A "frontend task" is any task whose **Files:** list contains a `.tsx`, `.jsx`, `.css`, `.scss`, `.html`, `.svelte`, `.vue`, or `.astro` path.
+
+Every frontend task MUST include a `**Design:**` field with:
+- `Register: brand` or `Register: product`
+- `Tokens used:` non-empty list of CSS custom properties (e.g. `var(--accent), --space-4`) — proves the task references DESIGN.md tokens, not raw hex/px
+- `Scope: component|section|page|app`
+- `Anti-pattern guard:` line confirming builder runs `bin/slop-detect.mjs` pre-commit
+
+**FAIL if:**
+- Frontend task missing `**Design:**` field entirely
+- Register is neither `brand` nor `product`
+- Tokens used is empty or contains raw hex (`#ff0000`) instead of CSS-var references
+- Plan steps on absolute bans (per `rules/design-laws.md` §8): grep the plan for `gradient text`, `glassmorphism`, `purple gradient`, `hero metric template`, `identical card grid`, `modal as first thought`, `border-left:.4px` decorative, `font-family: Inter`, `Space Grotesk`. Any hit = REVISE.
+
+Non-frontend tasks (backend, migrations, API routes without UI) MUST NOT have a `**Design:**` field. Warn but don't fail if one is mistakenly added.
+
 ### Rule 8: Validation commands test behavior, not just existence
 
 Each task's `**Validation:**` list must contain at least one `grep-match` or `command-exit` check — a command that proves the code DOES something. A task whose ONLY validation is `test -f {file}` will pass even if the file contains only `// TODO`.

package/agents/planner.md

@@ -11,6 +11,9 @@ You create phase plans. Plans are prompts — they ARE the instructions the buil
 ## Input
 
 - `<project_context>` — inlined `.planning/PROJECT.md` contents
+- `<product_context>` — inlined `PRODUCT.md` (if present — required from v4.5.0 onward; substrate for any frontend task)
+- `<design_spec>` — inlined `DESIGN.md` (if present — visual contract for any frontend task)
+- `<design_substrate>` — inlined `rules/design-laws.md` + matching register file (`rules/design-brand.md` OR `rules/design-product.md` based on PRODUCT.md `register:` field)
 - `<current_state>` — inlined `.planning/STATE.md` contents
 - `<phase_details>` — phase goal + success criteria + REQ-IDs from ROADMAP.md
 - `<locked_decisions>` (optional) — Locked Decisions from `.planning/phase-{N}-context.md` if it exists
@@ -101,6 +104,12 @@ waves: {count}
 
 **Context:** Read @{file references}
 
+**Design:** (REQUIRED for any task touching .tsx/.jsx/.css/.scss/.html — omit otherwise)
+- Register: {brand|product}
+- Tokens used: {var(--accent), var(--text), --space-4, ...}
+- Scope: {component|section|page|app}
+- Anti-pattern guard: builder runs `node bin/slop-detect.mjs {target}` pre-commit; commit blocked on critical findings
+
 ## Success Criteria
 - [ ] {phase-level truth 1}
 - [ ] {phase-level truth 2}

package/agents/verifier.md

@@ -14,6 +14,9 @@ You verify that a phase achieved its GOAL, not just completed its TASKS.
 
 - `<plan_path>` — path to `.planning/phase-{N}-plan.md`
 - `<project_context>` — inlined `.planning/PROJECT.md` contents (for Quality scoring against project conventions)
+- `<product_context>` — inlined `PRODUCT.md` (if present, v4.5.0+) — register, anti-references, principles
+- `<design_spec>` — inlined `DESIGN.md` (if present) — visual contract for design rubric scoring
+- `<design_substrate>` — inlined `rules/design-laws.md`, `rules/design-rubric.md`, and the matching register file
 - `<previous_verification>` (optional) — inlined `.planning/phase-{N}-verification.md` from a prior run
 
 ## Output
@@ -118,6 +121,65 @@ grep -c "async.*=> {}\|() => {}" {file}
 
 If Level 2 finds more than 2 stub patterns in a single file, mark that criterion as **FAIL** regardless of other checks. Stubs are not implementations.
 
+## Design Verification (v4.5.0+)
+
+If the phase touched any frontend file (`.tsx/.jsx/.css/.scss/.html`), run the design verification block IN ADDITION to the functional verification above. Design FAIL blocks the phase the same way a functional FAIL does.
+
+### Step A — slop-detect gate (must pass)
+
+```bash
+node bin/slop-detect.mjs {touched frontend paths from git diff}
+```
+
+If exit code is 1 (critical findings present), the phase FAILS. Quote the findings in the report. Do not score the rubric — fix slop first.
+
+### Step B — Design rubric scoring (8 dimensions)
+
+Apply `rules/design-rubric.md`. Score 1-5 per dimension WITH evidence on the next line. Default to 3 unless evidence supports otherwise.
+
+Scoped by phase scope:
+- Component-only phase → score Typography, Color cohesion, States, Motion intent, Microcopy, Container depth (skip Layout originality, Spatial rhythm — those are page-level concerns)
+- Page/section phase → all 8 dimensions
+- Full app phase → all 8 dimensions across 2-3 representative routes, average
+
+Output format (mandatory, append to verification.md):
+
+```markdown
+## Design Rubric — Phase {N}
+
+| Dim | Score | Evidence |
+|---|---|---|
+| Typography | 4 | `app/page.tsx:14` Fraunces + JetBrains Mono pair, weights 400/500/700 |
+| Color cohesion | 3 | All CSS vars in `app/globals.css:8-22`, OKLCH used, strategy: Restrained |
+| ... | ... | ... |
+
+**Aggregate:** {sum}/40 (avg {sum/8})
+**Design verdict:** PASS (all dims ≥ 3) | FAIL (Layout Originality at 2 — three-column grid, see `app/page.tsx:42`)
+```
+
+### Step C — Drift audit (full app verification only)
+
+Compare implementation against DESIGN.md tokens. Flag tokens used in code but not declared, and raw hex values still appearing.
+
+```bash
+# Orphan tokens (used in code, missing from DESIGN.md)
+grep -rE "var\(--[a-z-]+\)" src/ app/ components/ 2>/dev/null | \
+  awk -F'var\\(--' '{print $2}' | awk -F'\\)' '{print $1}' | sort -u > /tmp/used-tokens
+grep -E "^\s*--[a-z-]+:" DESIGN.md 2>/dev/null | sed -E 's/.*--([a-z-]+):.*/\1/' | sort -u > /tmp/declared
+comm -23 /tmp/used-tokens /tmp/declared
+```
+
+Drift findings are reported, not auto-failing. Drift may be intentional. But if 5+ orphan tokens appear, flag as MEDIUM finding for the next polish cycle.
+
+### Phase verdict (combined)
+
+```
+phase_pass = functional_pass AND slop_detect_pass AND design_rubric_pass
+phase_fail = ANY of the above failed
+```
+
+A perfect functional verification with a Design Rubric score of 2 in any dimension is a phase FAIL. Design is not a "would be nice" — it's a verification dimension equal to functionality.
+
 ### Wiring Check (Level 3)
 
 ```bash

package/bin/cli.js

@@ -160,10 +160,15 @@ const QUALIA_AGENT_FILES = [
 ];
 
 // 3 Qualia bin scripts.
-const QUALIA_BIN_FILES = ["state.js", "qualia-ui.js", "statusline.js", "knowledge.js", "knowledge-flush.js", "plan-contract.js", "agent-runs.js"];
-
-// 6 Qualia rules.
-const QUALIA_RULE_FILES = ["security.md", "frontend.md", "design-reference.md", "deployment.md", "infrastructure.md", "grounding.md"];
+const QUALIA_BIN_FILES = ["state.js", "qualia-ui.js", "statusline.js", "knowledge.js", "knowledge-flush.js", "plan-contract.js", "agent-runs.js", "slop-detect.mjs"];
+
+// Qualia rules — security, deployment, infra, grounding, plus the v4.5.0 design substrate.
+// frontend.md and design-reference.md are kept for backward compat; new projects use design-laws/brand/product/rubric.
+const QUALIA_RULE_FILES = [
+  "security.md", "deployment.md", "infrastructure.md", "grounding.md",
+  "frontend.md", "design-reference.md",
+  "design-laws.md", "design-brand.md", "design-product.md", "design-rubric.md",
+];
 
 function promptYesNo(question, defaultYes) {
   return new Promise((resolve) => {
@@ -1215,7 +1220,7 @@ function cmdHelp() {
   console.log(`    ${TG}/qualia-plan${RESET}     Plan a phase`);
   console.log(`    ${TG}/qualia-build${RESET}    Build it (parallel tasks)`);
   console.log(`    ${TG}/qualia-verify${RESET}   Verify it works`);
-  console.log(`    ${TG}/qualia-design${RESET}   One-shot design fix`);
+  console.log(`    ${TG}/qualia-polish${RESET}   Design pass — any scope (component, route, app, redesign)`);
   console.log(`    ${TG}/qualia-debug${RESET}    Structured debugging`);
   console.log(`    ${TG}/qualia-review${RESET}   Production audit`);
   console.log(`    ${TG}/qualia-ship${RESET}     Deploy to production`);

package/bin/install.js

@@ -432,6 +432,12 @@ async function main() {
       path.join(binDest, "agent-runs.js")
     );
     ok("agent-runs.js (agent telemetry writer)");
+    copy(
+      path.join(FRAMEWORK_DIR, "bin", "slop-detect.mjs"),
+      path.join(binDest, "slop-detect.mjs")
+    );
+    fs.chmodSync(path.join(binDest, "slop-detect.mjs"), 0o755);
+    ok("slop-detect.mjs (anti-pattern scanner — runs pre-commit on frontend builds)");
   } catch (e) {
     warn(`scripts — ${e.message}`);
   }

package/bin/slop-detect.mjs

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+/**
+ * slop-detect — Standalone anti-pattern scanner for Qualia projects.
+ *
+ * Usage:
+ *   node bin/slop-detect.mjs                       # scan whole repo (default globs)
+ *   node bin/slop-detect.mjs path/to/file.tsx      # scan one file
+ *   node bin/slop-detect.mjs src/components/       # scan a directory
+ *   node bin/slop-detect.mjs --json                # machine-readable output
+ *   node bin/slop-detect.mjs --severity=critical   # only critical findings
+ *
+ * Exit codes:
+ *   0  no critical findings
+ *   1  one or more critical findings
+ *   2  invocation error
+ *
+ * Builder agents call this BEFORE commit. A non-zero exit blocks the commit.
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, extname, relative, resolve } from "node:path";
+import { argv, exit, cwd } from "node:process";
+
+// ── Severity rubric (from rules/grounding.md) ─────────────────────────
+const CRITICAL = "critical";
+const HIGH = "high";
+const MEDIUM = "medium";
+const LOW = "low";
+
+// ── Anti-patterns ─────────────────────────────────────────────────────
+// Each rule: { id, severity, label, fileGlob, pattern, allow?, fix }
+const RULES = [
+  // ── CRITICAL: absolute bans (block commit) ──────────────────────────
+  {
+    id: "ABS-FONT",
+    severity: CRITICAL,
+    label: "Banned font (Inter/Roboto/Arial/system-ui/Space Grotesk)",
+    fileGlob: /\.(tsx|jsx|ts|js|css|scss|html|svelte|vue|astro)$/,
+    pattern: /(font-family|fontFamily)[^;{,]*(['"`])(Inter|Roboto|Arial|Helvetica|system-ui|Space\s*Grotesk)\b/i,
+    allow: /Inter\s*Display|Inter\s*Tight/,
+    fix: "Replace with a distinctive font (Fraunces, Geist, Söhne, JetBrains Mono, etc). See DESIGN.md §3.",
+  },
+  {
+    id: "ABS-PURPLE-GRAD",
+    severity: CRITICAL,
+    label: "Purple-blue gradient (the #1 AI-design tell)",
+    fileGlob: /\.(tsx|jsx|ts|js|css|scss|html|svelte|vue|astro)$/,
+    pattern: /(from-(blue|indigo|violet)-\d+\s+to-(purple|violet|fuchsia|pink)-\d+|from-(purple|violet|fuchsia|pink)-\d+\s+to-(blue|indigo|violet)-\d+|linear-gradient[^;]*(blue|indigo)[^;]*(purple|violet|fuchsia)|linear-gradient[^;]*(purple|violet|fuchsia)[^;]*(blue|indigo))/i,
+    fix: "Use one solid brand accent color. Emphasis via weight or size, not gradient text/bg.",
+  },
+  {
+    id: "ABS-GRADIENT-TEXT",
+    severity: CRITICAL,
+    label: "Gradient text (background-clip: text)",
+    fileGlob: /\.(tsx|jsx|ts|js|css|scss|html|svelte|vue|astro)$/,
+    pattern: /(background-clip\s*:\s*text|bg-clip-text|-webkit-background-clip\s*:\s*text)/i,
+    fix: "Decorative, never meaningful. Use a single solid color. Emphasis via weight or size.",
+  },
+  {
+    id: "ABS-PURE-BLACK-WHITE",
+    severity: CRITICAL,
+    label: "Pure #000 or #fff (untuned, generic)",
+    fileGlob: /\.(tsx|jsx|ts|js|css|scss)$/,
+    pattern: /#(000000|FFFFFF|000|FFF)\b/,
+    allow: /shadow|outline|currentColor|var\(/i,
+    fix: "Tint every neutral toward brand hue. Use OKLCH with chroma 0.005-0.015. See design-laws.md §1.",
+  },
+  {
+    id: "ABS-HEX-IN-JSX",
+    severity: CRITICAL,
+    label: "Hardcoded hex color in JSX/TSX (use design tokens)",
+    fileGlob: /\.(tsx|jsx)$/,
+    pattern: /style=\{[^}]*['"]#[0-9a-fA-F]{3,8}['"]/,
+    fix: "Move color to a CSS custom property in DESIGN.md tokens. Reference via var(--name).",
+  },
+  {
+    id: "ABS-SIDE-STRIPE",
+    severity: CRITICAL,
+    label: "Side-stripe border (decorative border-left ≥2px)",
+    fileGlob: /\.(tsx|jsx|ts|js|css|scss)$/,
+    pattern: /border-(left|right)\s*:\s*\d+(px|rem)\s+solid|border-l-(2|4|8)|border-r-(2|4|8)/,
+    allow: /focus|active|outline/,
+    fix: "Use full borders, background tints, leading icons, or nothing. See design-laws.md §8.",
+  },
+
+  // ── HIGH: strong tells ───────────────────────────────────────────────
+  {
+    id: "HI-MAX-W-CAP",
+    severity: HIGH,
+    label: "Hardcoded max-width container (no fluid full-width)",
+    fileGlob: /\.(tsx|jsx|ts|js|css|scss)$/,
+    pattern: /(max-w-7xl|max-w-\[1200|max-w-\[1280|max-w-\[1440|max-width\s*:\s*1200|max-width\s*:\s*1280)/,
+    fix: "Use fluid padding: clamp(1rem, 5vw, 4rem). Cap content via max-width: 65ch on prose only.",
+  },
+  {
+    id: "HI-OUTLINE-NONE",
+    severity: HIGH,
+    label: "outline:none without focus replacement (a11y violation)",
+    fileGlob: /\.(tsx|jsx|ts|js|css|scss)$/,
+    pattern: /outline\s*:\s*none|outline-none/,
+    allow: /focus-visible|focus:ring|focus:outline/,
+    fix: "Replace with a visible focus ring: 2px offset, contrasting color. See design-laws.md §accessibility.",
+  },
+  {
+    id: "HI-IMG-NO-ALT",
+    severity: HIGH,
+    label: "<img> without alt attribute",
+    fileGlob: /\.(tsx|jsx|html|svelte|vue|astro)$/,
+    pattern: /<img\s+(?![^>]*\balt=)[^>]*>/,
+    fix: "Every image needs alt text. Decorative: alt=\"\" + aria-hidden=\"true\". Meaningful: describe it.",
+  },
+  {
+    id: "HI-GENERIC-CTA",
+    severity: HIGH,
+    label: "Generic CTA copy (Get Started / Learn More / Click Here)",
+    fileGlob: /\.(tsx|jsx|html|svelte|vue|astro|md)$/,
+    pattern: />\s*(Get Started|Learn More|Click Here|Welcome to|Read More|Find Out More)\s*</i,
+    fix: "Name the action: 'Download invoice', 'Continue setup', 'Try the demo'.",
+  },
+  {
+    id: "HI-EM-DASH",
+    severity: HIGH,
+    label: "Em dash in user-facing copy (— or '--')",
+    // Scope: shipped UI files only. Markdown / docs prose is allowed em-dashes.
+    fileGlob: /\.(tsx|jsx|html|svelte|vue|astro)$/,
+    pattern: />\s*[^<]*[—][^<]*</,
+    fix: "Use commas, colons, semicolons, periods, or parentheses. See design-laws.md §7.",
+  },
+
+  // ── MEDIUM: noisy signals ────────────────────────────────────────────
+  {
+    id: "MED-CARD-GRID-3",
+    severity: MEDIUM,
+    label: "Three/four-column card grid (likely identical-card slop)",
+    fileGlob: /\.(tsx|jsx|html|svelte|vue|astro)$/,
+    pattern: /(grid-cols-3|grid-cols-4|grid-template-columns\s*:\s*repeat\(\s*[34]\s*,)/,
+    fix: "Vary card sizes and content shapes. Identical cards in a grid is the AI default hero pattern.",
+  },
+  {
+    id: "MED-GLASSMORPHISM",
+    severity: MEDIUM,
+    label: "Glassmorphism (backdrop-blur on multiple surfaces — likely default)",
+    fileGlob: /\.(tsx|jsx|css|scss)$/,
+    pattern: /(backdrop-blur|backdrop-filter\s*:\s*blur)/,
+    fix: "Glass effects are rare and purposeful, or nothing. Don't use them as default decoration.",
+  },
+  {
+    id: "MED-CONTAINER-DEPTH",
+    severity: MEDIUM,
+    label: "Possible container-depth >2 (card on card on pill)",
+    fileGlob: /\.(tsx|jsx)$/,
+    pattern: /<div[^>]*className="[^"]*\b(card|panel|surface)[^"]*"[^>]*>\s*<div[^>]*className="[^"]*\b(card|panel|surface)/,
+    fix: "Container depth max 2. Flatten nested cards into a single container with content.",
+  },
+  {
+    id: "MED-ANIMATE-LAYOUT",
+    severity: MEDIUM,
+    label: "Animating layout properties (causes reflow, jank)",
+    fileGlob: /\.(tsx|jsx|css|scss)$/,
+    pattern: /transition\s*:\s*(width|height|top|left|right|bottom|margin|padding)\s/,
+    fix: "Animate transform and opacity only. Layout properties trigger reflow.",
+  },
+  {
+    id: "MED-BOUNCE-EASING",
+    severity: MEDIUM,
+    label: "Bounce/elastic easing (banned per design-laws.md §6)",
+    fileGlob: /\.(tsx|jsx|css|scss|js|ts)$/,
+    pattern: /(bounce|elastic|backIn|backOut|cubic-bezier\([^)]*1\.\d+)/i,
+    fix: "Ease out with exponential curves: cubic-bezier(0.22, 1, 0.36, 1) or (0.16, 1, 0.3, 1).",
+  },
+
+  // ── LOW: cleanup ─────────────────────────────────────────────────────
+  {
+    id: "LOW-CONSOLE-LOG",
+    severity: LOW,
+    label: "console.log in production code",
+    fileGlob: /\.(tsx|jsx|ts|js)$/,
+    pattern: /console\.(log|debug)\(/,
+    allow: /\/\/\s*(debug|todo)|test\.|spec\./i,
+    fix: "Remove or replace with a proper logger.",
+  },
+];
+
+// ── File walker ───────────────────────────────────────────────────────
+const SKIP_DIRS = new Set([
+  "node_modules", ".next", "dist", "build", ".git", ".turbo",
+  "coverage", ".cache", "out", ".vercel", ".vscode", ".idea",
+  ".planning", ".qa-screenshots",
+]);
+
+function* walk(dir) {
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+  for (const name of entries) {
+    if (name.startsWith(".") && !["src", "app", "components", "lib"].includes(name)) {
+      // skip dotfiles except known source dirs
+      if (SKIP_DIRS.has(name)) continue;
+    }
+    const path = join(dir, name);
+    let st;
+    try { st = statSync(path); } catch { continue; }
+    if (st.isDirectory()) {
+      if (SKIP_DIRS.has(name)) continue;
+      yield* walk(path);
+    } else if (st.isFile()) {
+      yield path;
+    }
+  }
+}
+
+// ── Scanner ───────────────────────────────────────────────────────────
+function scanFile(path) {
+  const findings = [];
+  let content;
+  try { content = readFileSync(path, "utf8"); } catch { return findings; }
+  const lines = content.split("\n");
+
+  for (const rule of RULES) {
+    if (!rule.fileGlob.test(path)) continue;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (!rule.pattern.test(line)) continue;
+      if (rule.allow && rule.allow.test(line)) continue;
+      findings.push({
+        rule: rule.id,
+        severity: rule.severity,
+        label: rule.label,
+        file: path,
+        line: i + 1,
+        snippet: line.trim().slice(0, 120),
+        fix: rule.fix,
+      });
+    }
+  }
+  return findings;
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const args = { paths: [], json: false, severity: null, help: false };
+  for (const a of argv.slice(2)) {
+    if (a === "--json") args.json = true;
+    else if (a === "--help" || a === "-h") args.help = true;
+    else if (a.startsWith("--severity=")) args.severity = a.split("=")[1];
+    else if (a.startsWith("--")) {
+      console.error(`Unknown flag: ${a}`);
+      exit(2);
+    } else args.paths.push(a);
+  }
+  return args;
+}
+
+function help() {
+  console.log(`slop-detect — Qualia anti-pattern scanner
+
+Usage:
+  slop-detect [path ...] [--json] [--severity=critical|high|medium|low]
+
+Examples:
+  slop-detect                              # scan whole repo
+  slop-detect src/components/Button.tsx    # scan one file
+  slop-detect app/                         # scan a directory
+  slop-detect --severity=critical          # only critical findings
+  slop-detect --json > slop.json           # machine-readable
+
+Exit codes:
+  0  no critical findings
+  1  one or more critical findings
+  2  invocation error
+`);
+}
+
+function severityOrder(s) { return { critical: 4, high: 3, medium: 2, low: 1 }[s] || 0; }
+function severityColor(s) { return { critical: "\x1b[31m", high: "\x1b[33m", medium: "\x1b[36m", low: "\x1b[37m" }[s] || ""; }
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+
+function main() {
+  const args = parseArgs(argv);
+  if (args.help) { help(); exit(0); }
+
+  const targets = args.paths.length ? args.paths.map(p => resolve(p)) : ["app", "components", "src", "lib", "pages"]
+    .map(d => resolve(cwd(), d))
+    .filter(d => existsSync(d));
+
+  if (targets.length === 0) targets.push(resolve(cwd()));
+
+  // Collect files
+  const files = [];
+  for (const t of targets) {
+    let st;
+    try { st = statSync(t); } catch {
+      console.error(`Path does not exist: ${t}`);
+      exit(2);
+    }
+    if (st.isFile()) files.push(t);
+    else for (const f of walk(t)) files.push(f);
+  }
+
+  // Scan
+  const findings = [];
+  for (const f of files) findings.push(...scanFile(f));
+
+  // Filter by severity
+  const minSev = args.severity ? severityOrder(args.severity) : 1;
+  const filtered = findings.filter(f => severityOrder(f.severity) >= minSev);
+
+  // Output
+  if (args.json) {
+    console.log(JSON.stringify({
+      scanned_files: files.length,
+      total_findings: filtered.length,
+      by_severity: {
+        critical: filtered.filter(f => f.severity === CRITICAL).length,
+        high: filtered.filter(f => f.severity === HIGH).length,
+        medium: filtered.filter(f => f.severity === MEDIUM).length,
+        low: filtered.filter(f => f.severity === LOW).length,
+      },
+      findings: filtered,
+    }, null, 2));
+  } else {
+    if (filtered.length === 0) {
+      console.log(`${BOLD}\x1b[32m✓ no slop detected${RESET}  (${files.length} files scanned)`);
+    } else {
+      // Group by severity, sorted highest first
+      const bySev = {};
+      for (const f of filtered) (bySev[f.severity] ||= []).push(f);
+      const order = ["critical", "high", "medium", "low"];
+      for (const sev of order) {
+        const items = bySev[sev];
+        if (!items) continue;
+        const color = severityColor(sev);
+        console.log(`\n${color}${BOLD}${sev.toUpperCase()}${RESET}  ${items.length} finding${items.length === 1 ? "" : "s"}`);
+        console.log(`${DIM}${"─".repeat(60)}${RESET}`);
+        for (const f of items) {
+          const rel = relative(cwd(), f.file);
+          console.log(`${color}●${RESET} ${BOLD}${rel}:${f.line}${RESET}  ${DIM}[${f.rule}]${RESET}`);
+          console.log(`  ${f.label}`);
+          console.log(`  ${DIM}${f.snippet}${RESET}`);
+          console.log(`  ${color}→${RESET} ${f.fix}`);
+          console.log();
+        }
+      }
+      const crit = (bySev.critical || []).length;
+      const total = filtered.length;
+      console.log(`${BOLD}${total}${RESET} total · ${BOLD}${crit}${RESET} critical · ${files.length} files scanned`);
+      if (crit > 0) console.log(`${severityColor("critical")}${BOLD}commit blocked${RESET} — fix critical findings first`);
+    }
+  }
+
+  // Exit code
+  const criticalCount = filtered.filter(f => f.severity === CRITICAL).length;
+  exit(criticalCount > 0 ? 1 : 0);
+}
+
+main();