qualia-framework 4.3.0 → 4.5.0

package/rules/design-rubric.md

@@ -0,0 +1,153 @@
+# 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/skills/qualia-build/SKILL.md

@@ -32,9 +32,9 @@ cat .planning/phase-{N}-plan.md
 
 Parse: tasks, waves, file references.
 
-### 1b. Create Recovery Point
+### 1b. Create Recovery Reference
 
-Before executing any tasks, tag current HEAD for rollback:
+Before executing any tasks, record current HEAD for diagnosis. This is a reference, not an automatic rollback instruction.
 
 ```bash
 git tag -f "pre-build-phase-{N}" HEAD 2>/dev/null
@@ -44,10 +44,10 @@ git tag -f "pre-build-phase-{N}" HEAD 2>/dev/null
 node ~/.claude/bin/qualia-ui.js info "Recovery point: pre-build-phase-{N}"
 ```
 
-If a wave fails and the user needs to roll back:
+If a wave fails, stop and inspect `git status` plus the failed task output. Do not run destructive rollback commands automatically. Preserve user work, then either fix forward or ask before reverting specific files.
 ```bash
-git reset --hard pre-build-phase-{N}
-node ~/.claude/bin/state.js transition --to planned --force
+git status --short
+git diff --stat
 ```
 
 ### 2. Execute Waves

package/skills/qualia-flush/SKILL.md

@@ -30,7 +30,7 @@ the same — manually-triggered, internal-data only, no vector DB.
 - **Manually:** `/qualia-flush` whenever the daily-log feels rich. Once a week
   is the recommended cadence. More than once a day is wasteful — the
   signal-to-noise ratio is too low at single-day windows.
-- **Automatically:** not yet wired. v4.3.0 will add a cron-friendly
+- **CLI runner:** `qualia-framework flush` wraps the cron-friendly
   `bin/knowledge-flush.js` non-interactive runner.
 
 ## Inputs

package/skills/qualia-new/SKILL.md

@@ -107,6 +107,25 @@ git add .planning/PROJECT.md
 git commit -m "docs: initialize project"
 ```
 
+### Step 5b. Write PRODUCT.md (v4.5.0 — REQUIRED)
+
+`PRODUCT.md` is the "who and why" every road agent reads before designing or building. It is **required** — the planner, builder, and verifier all load it as substrate.
+
+Ask the user 5 short questions (one at a time, each with a sensible default they can `[Enter]` past):
+
+1. **Register** — "Is this design IS the product (marketing/landing/portfolio → `brand`) or design SERVES the product (app/admin/dashboard → `product`)?" Default: infer from project type.
+2. **Three users** — "Name 3 specific humans who will use this. Not personas — real names + their workflow scenario." Default: project type defaults.
+3. **Brand voice** — "Three adjectives, then one paragraph showing the voice in motion (an error message, a confirmation, an empty state)." Default: derive from PROJECT.md.
+4. **Anti-references** — "Three sites this should NOT look like, with why." Required, no defaults — anti-references are more useful than positive references.
+5. **One-sentence differentiation** — "What does someone remember 24 hours after first using this?" Required.
+
+Write `.planning/PRODUCT.md` from `templates/PRODUCT.md`, filling the user's answers.
+
+```bash
+git add .planning/PRODUCT.md
+git commit -m "docs: PRODUCT.md — register, users, voice, anti-references"
+```
+
 ### Step 6. Create config.json
 
 ```json
@@ -124,13 +143,31 @@ git commit -m "docs: initialize project"
 
 **Note:** `workflow.research` is ALWAYS `true` for v4. It exists for telemetry but is no longer read as a gate.
 
-### Step 7. Create DESIGN.md (frontend projects)
+### Step 7. Create DESIGN.md (frontend projects — v4.5.0 OKLCH-first)
+
+If frontend work is involved, generate `.planning/DESIGN.md` from `templates/DESIGN.md`. The generation MUST commit to four things upfront (these go in §1 of DESIGN.md):
+
+1. **Aesthetic direction** — pick ONE: `editorial · brutalist · luxury · maximalist · retro-futuristic · organic · terminal-native · sci-fi · pastoral · industrial · ...`. Don't hedge ("modern minimal" is hedging — pick one extreme).
+2. **Color strategy** — pick ONE: `Restrained · Committed · Full palette · Drenched`. See `rules/design-laws.md` §2.
+3. **Scene sentence** — one concrete sentence: who uses this, where, ambient light, mood. NOT "observability dashboard" — "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room." Run the sentence, not the category.
+4. **Differentiation** — one sentence: what someone remembers 24 hours later.
+
+Then fill the rest of DESIGN.md:
+- §2 Color: OKLCH only, no `#000`/`#fff`, neutrals tinted toward brand hue (chroma 0.005-0.015), accent within the chosen strategy
+- §3 Typography: distinctive display + refined body pair. **NEVER** Inter, Roboto, Arial, Helvetica, system-ui, Space Grotesk
+- §4 Spacing: 8px grid + fluid `clamp()` for page padding
+- §5 Components: token-driven button/input/card/table specs
+- §6 Depth: 3-level shadow elevation, OKLCH-tinted (not gray)
+- §7 Motion: easing tokens (ease-out-quart/expo), no bounce, `prefers-reduced-motion` respected
+- §8 Iconography: ONE family
+- §9 Responsive: mobile-first
+- §10 Anti-pattern checklist (the auto-runnable one)
 
-If frontend work is involved, generate `.planning/DESIGN.md` from the template with concrete palette, distinctive typography (NEVER Inter/Roboto/system-ui), 8px spacing grid, motion approach, component patterns.
+Cross-check the result against `rules/design-laws.md` §8 absolute bans BEFORE writing — the design must not propose any banned pattern.
 
 ```bash
 git add .planning/DESIGN.md .planning/config.json
-git commit -m "docs: design direction + config"
+git commit -m "docs: DESIGN.md — direction commit + OKLCH palette + tokens"
 ```
 
 ### Step 8. Run Research (ALWAYS, no permission ask)