qualia-framework 5.9.0 → 6.1.0

package/skills/qualia-new/SKILL.md

@@ -46,11 +46,33 @@ Initialize a project with the **entire arc mapped from kickoff to handoff**. All
 node ~/.claude/bin/qualia-ui.js banner new
 ```
 
-Then say: **"Let's build something. Tell me what you want to make."**
+Banner only. Do NOT ask anything yet. The next thing the user sees is the project-shape gate — not a free-text "tell me what to build". Shape gate first, content second, because the shape drives the question set.
 
-Wait for free-text answer. Do NOT use AskUserQuestion here — let them talk naturally.
+### Step 1. Project Type Gate (Demo vs Full vs Quick) — FIRST QUESTION
 
-### Step 0.5. Brownfield Check
+The single most important fork. Demo and Full produce different journeys, different research depth, different milestone counts. This is the literal first interaction with the user.
+
+Use **AskUserQuestion** (interactive UI — never a plain-text prompt):
+
+- header: "Project shape"
+- question: "What kind of project is this? Pick one — it drives everything else."
+- options:
+  - "Demo" — one shippable milestone, real backend, no mocks. Built to win a client conversation, extensible via `/qualia-milestone` if they sign. 8-question discovery.
+  - "Full project" — the multi-milestone arc to Handoff. 2-5 milestones planned upfront. 14-question discovery.
+  - "Quick prototype" — landing page, throwaway, ≤1 day. Skips research and journey. (Equivalent to `--quick` flag.)
+
+Store the answer as `PROJECT_TYPE=demo` | `PROJECT_TYPE=full` | `PROJECT_TYPE=quick`. It drives every downstream step.
+
+**Demo design philosophy is non-negotiable (do NOT compromise on these regardless of speed pressure):**
+- **1 milestone only.** No multi-milestone arc, no Handoff phase. The demo IS the artifact.
+- **NO mock data.** Real backend, real database, real auth. Hardcoded JSON in components is a hard-block. If the data needs Supabase, ship Supabase.
+- **Real agent/platform functionality.** The thing actually works end-to-end. A demo with broken flows is not a Qualia demo.
+- **DESIGN.md mandatory.** OKLCH palette, distinctive typography, full token system. Slop-detect runs hard-block.
+- **Focus = design + functionality.** No sales decks, no placeholder copy, no "lorem ipsum" anywhere.
+
+Speed in a demo comes from skipping multi-milestone planning, NEVER from skipping design quality, mocking the backend, or cutting corners on the core flow.
+
+### Step 2. Brownfield Check
 
 ```bash
 test -f package.json && echo "HAS_PACKAGE"
@@ -58,23 +80,27 @@ test -d .git && echo "HAS_GIT"
 test -f .planning/codebase/README.md && echo "ALREADY_MAPPED"
 ```
 
-If existing code is detected AND not already mapped, ask the user whether to run `/qualia-map` inline first. If yes, invoke the `qualia-map` skill inline, wait for completion, then continue to Step 0.6.
+If existing code is detected AND not already mapped, **AskUserQuestion**:
 
-### Step 0.6. Project Type Gate (Demo vs Full)
+- header: "Existing code detected"
+- question: "Run `/qualia-map` to scan the repo first?"
+- options: ["Yes — map it", "No — proceed without mapping"]
 
-The single most important fork in the workflow. Demo and Full produce different journeys, different research depth, different milestone counts.
+If yes, invoke the `qualia-map` skill inline, wait for completion, then continue. If quick prototype + brownfield, skip the map (quick is for greenfield trivial work; brownfield + quick is contradictory — route to `/qualia-feature` instead).
 
-- header: "Project shape"
-- question: "Is this a demo (single shippable milestone, sales conversation) or a full project (multi-milestone arc to Handoff)?"
-- options:
-  - "Demo" — one shippable milestone, real backend, no mocks. Built to win a client conversation, extensible via `/qualia-milestone` if they sign.
-  - "Full project" — the full multi-milestone arc to Handoff. 2-5 milestones planned upfront.
+### Step 3. One-line Pitch (free-text — minimal, no clarification round)
+
+The shape is locked, now capture the content in one sentence:
+
+> **"What are you building? One sentence — a stranger should understand it."**
+
+Accept whatever the user says, even if broad. **Do NOT start an ad-hoc clarification round here.** Depth comes from the structured discovery interview in Step 4, not from free-form questioning. If the answer is "a SaaS platform" — that's fine, write it down, move on. `/qualia-discuss` will refine it through its 8 or 14 structured questions.
 
-Store the answer as `PROJECT_TYPE=demo` or `PROJECT_TYPE=full`. It drives Steps 1, 8, and 10.
+This is the ONLY free-text question in the kickoff flow. Everything else is `AskUserQuestion`.
 
-**Demo design philosophy is non-negotiable:** real backend always, DESIGN.md mandatory, slop-detect hard-block. Speed comes from skipping multi-milestone planning, NEVER from skipping design quality or mocking the backend.
+### Step 4. Mandatory Discovery Interview (PROJECT MODE)
 
-### Step 1. Mandatory Discovery Interview (PROJECT MODE)
+**Hard rule:** This is the next tool call after Step 3. No ad-hoc clarification, no free-form follow-up, no "let me ask a few quick things first." If the one-line pitch was "a SaaS platform", you invoke `/qualia-discuss` NOW — that skill's structured questions are how breadth gets refined into depth.
 
 Invoke `/qualia-discuss` inline in PROJECT MODE — non-technical kickoff interview. 8 questions for demo, 14 for full project. Pass `PROJECT_TYPE` so the discuss skill skips the type question.
 
@@ -94,11 +120,11 @@ After the interview returns, `.planning/project-discovery.md` exists with the us
 
 If "More questions": re-invoke `/qualia-discuss` for additional rounds. Otherwise continue.
 
-### Step 2. Detect Project Type
+### Step 5. Detect Project Type
 
-From questioning answers, infer type → `website` | `ai-agent` | `voice-agent` | `mobile-app` | `null`. If matched, `cat ~/.claude/qualia-templates/projects/{type}.md` gives suggested milestone arc. Store `template_type` for Step 10.
+From questioning answers, infer type → `website` | `ai-agent` | `voice-agent` | `mobile-app` | `null`. If matched, `cat ~/.claude/qualia-templates/projects/{type}.md` gives suggested milestone arc. Store `template_type` for Step 13.
 
-### Step 3. Design Direction (frontend only)
+### Step 6. Design Direction (frontend only)
 
 - header: "Design"
 - question: "What's the design vibe?"
@@ -106,7 +132,7 @@ From questioning answers, infer type → `website` | `ai-agent` | `voice-agent`
 
 Plus free-text: "Any brand colors or reference sites I should look at?"
 
-### Step 4. Client Context
+### Step 7. Client Context
 
 - header: "Client"
 - question: "Client project or internal?"
@@ -117,7 +143,7 @@ If client, ask name. Check saved prefs:
 node ~/.claude/bin/knowledge.js search "{client name}"
 ```
 
-### Step 5. Write PROJECT.md
+### Step 8. Write PROJECT.md
 
 Create `.planning/PROJECT.md` from the template. Include: client, what we're building, core value, validated + active requirements (empty for greenfield), out of scope, stack, design direction, decisions table.
 
@@ -127,7 +153,7 @@ git add .planning/PROJECT.md
 git commit -m "docs: initialize project"
 ```
 
-### Step 5a. Seed CONTEXT.md and decisions/ (v5.0 — REQUIRED)
+### Step 8a. Seed CONTEXT.md and decisions/ (REQUIRED)
 
 The domain glossary is the single highest-leverage piece of substrate — every road agent loads it BEFORE PROJECT.md/DESIGN.md. Misalignment is the #1 failure mode in AI coding; CONTEXT.md kills it.
 
@@ -140,7 +166,7 @@ mkdir -p .planning/decisions
 cp ~/.claude/qualia-templates/decisions/ADR-template.md .planning/decisions/_template.md
 ```
 
-Then **seed the glossary from the questioning answers**. For each domain term that came up during Step 1 (Deep Questioning) — entities, actions, statuses, key nouns the user repeatedly said — add an entry to `.planning/CONTEXT.md` under `## Language` with:
+Then **seed the glossary from the questioning answers**. For each domain term that came up during the Step 4 `/qualia-discuss` interview — entities, actions, statuses, key nouns the user repeatedly said — add an entry to `.planning/CONTEXT.md` under `## Language` with:
 - the term
 - a one-sentence definition
 - an `Avoid:` line listing rejected synonyms (terms the team should NOT use for this concept)
@@ -156,7 +182,7 @@ git commit -m "docs: seed CONTEXT.md domain glossary + decisions/ folder"
 
 The glossary stays terse — one sentence per entry. It's loaded into every agent spawn; bloat costs tokens. `/qualia-discuss` will grow it inline as decisions crystallize during phase planning.
 
-### Step 5b. Write PRODUCT.md (v4.5.0 — REQUIRED)
+### Step 8b. Write PRODUCT.md (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.
 
@@ -175,7 +201,7 @@ git add .planning/PRODUCT.md
 git commit -m "docs: PRODUCT.md — register, users, voice, anti-references"
 ```
 
-### Step 6. Create config.json
+### Step 9. Create config.json
 
 ```json
 {
@@ -190,9 +216,9 @@ git commit -m "docs: PRODUCT.md — register, users, voice, anti-references"
 }
 ```
 
-**Note:** `workflow.research` is ALWAYS `true` for v4. It exists for telemetry but is no longer read as a gate.
+**Note:** `workflow.research` is always `true`. It exists for telemetry but is no longer read as a gate.
 
-### Step 7. Create DESIGN.md (frontend projects — v4.5.0 OKLCH-first)
+### Step 10. Create DESIGN.md (frontend projects — 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):
 
@@ -219,7 +245,7 @@ git add .planning/DESIGN.md .planning/config.json
 git commit -m "docs: DESIGN.md — direction commit + OKLCH palette + tokens"
 ```
 
-### Step 8. Run Research (ALWAYS, no permission ask)
+### Step 11. Run Research (ALWAYS, no permission ask)
 
 **In v4, research runs unconditionally.** The previous `workflow.research` gate is gone. Skipping research leads to generic roadmaps and surprises late in the project — the 4-agent cost is worth it.
 
@@ -253,7 +279,7 @@ node ~/.claude/bin/qualia-ui.js ok "Research complete"
 ```
 Display top 3 from SUMMARY.md (stack recommendation, table stakes, top pitfall).
 
-### Step 9. Feature Scoping (Multi-Milestone)
+### Step 12. Feature Scoping (Multi-Milestone)
 
 Read `.planning/research/FEATURES.md` and present the feature landscape. Features are scoped **to milestones** — you'll decide per-feature which milestone owns it.
 
@@ -271,7 +297,7 @@ Track selections:
 
 Gather any additional requirements the user wants that research missed.
 
-### Step 10. Run Roadmapper
+### Step 13. Run Roadmapper
 
 ```bash
 node ~/.claude/bin/qualia-ui.js banner roadmap
@@ -279,12 +305,12 @@ node ~/.claude/bin/qualia-ui.js banner roadmap
 
 **Roadmapper output branches on `PROJECT_TYPE`:**
 
-- **Demo** (`PROJECT_TYPE=demo`): roadmapper produces a 1-milestone JOURNEY.md (the demo milestone, 2-4 phases) plus a matching REQUIREMENTS.md and a fully-detailed ROADMAP.md. No "Handoff" milestone is appended — the demo is its own complete artifact. The journey-tree at Step 11 shows a single rung; the "extend to full project" branch is handled later by `/qualia-milestone` if the client signs.
+- **Demo** (`PROJECT_TYPE=demo`): roadmapper produces a 1-milestone JOURNEY.md (the demo milestone, 2-4 phases) plus a matching REQUIREMENTS.md and a fully-detailed ROADMAP.md. No "Handoff" milestone is appended — the demo is its own complete artifact. The journey-tree at Step 14 shows a single rung; the "extend to full project" branch is handled later by `/qualia-milestone` if the client signs.
 - **Full project** (`PROJECT_TYPE=full`): roadmapper produces the standard 2-5 milestone arc ending in Handoff. Milestone 1 fully detailed, M2..M{N-1} sketched (unless `--full-detail`).
 
 Spawn the roadmapper with `<project_type>$PROJECT_TYPE</project_type>` in the prompt. If the user passed `--full-detail`, include `<full_detail>true</full_detail>` so the roadmapper writes complete phase detail for ALL milestones (full project only; demo always has full detail because there's only one milestone). See REFERENCE.md section "Roadmapper prompt" for the verbatim prompt template.
 
-### Step 11. Present the Journey (single view)
+### Step 14. Present the Journey (single view)
 
 Render the branded journey ladder:
 
@@ -296,7 +322,7 @@ This shows M1..M{N} as a vertical ladder: shipped milestones get a green dot, cu
 
 Also narrate the one-glance summary. See REFERENCE.md section "Journey ladder format" for the ASCII template.
 
-### Step 12. Approval Gate (single — for the whole journey)
+### Step 15. Approval Gate (single — for the whole journey)
 
 - header: "Journey"
 - question: "Does this journey work for you?"
@@ -326,7 +352,7 @@ node ~/.claude/bin/qualia-ui.js info "Full phase detail for each later milestone
 
 (Skip this block when `--full-detail` was used — all milestones are already fully planned in that case.)
 
-### Step 13. Environment Setup
+### Step 16. Environment Setup
 
 Supabase project? `supabase link` or create. Vercel project? `vercel link`. Env vars? `.env.local` with placeholders from PROJECT.md stack.
 
@@ -337,7 +363,7 @@ git add .gitignore
 git commit -m "chore: environment setup" 2>/dev/null
 ```
 
-### Step 14. Auto-Apply Gate (or stop here)
+### Step 17. Auto-Apply Gate (or stop here)
 
 If invoked with `--auto`, skip straight into building Milestone 1:
 
@@ -390,15 +416,17 @@ Do NOT use `--quick` for: client projects, anything with compliance stakes, anyt
 
 ## Rules
 
-1. **Project type is the first fork.** Step 0.6 asks Demo vs Full Project. Every downstream step branches on this. Don't skip it, don't infer it.
-2. **Discovery interview is mandatory (v5.6).** Step 1 always invokes `/qualia-discuss` in PROJECT MODE. No free-form questioning loop, no "I'll just sketch PROJECT.md from the user's first message." The interview is 8 questions for demo, 14 for full project.
-3. **Research runs automatically.** No permission ask. Only `--quick` skips it. Demo path uses `<scope>quick</scope>` (3-call budget per researcher); full project uses standard 8-call budget.
-4. **Demo design philosophy is non-negotiable.** Real backend always, DESIGN.md mandatory, slop-detect hard-block. Speed comes from skipping multi-milestone planning, never from skipping design quality or mocking the backend. A demo that uses mock data is not a Qualia demo.
-5. **Demos are 1 milestone, full projects are 2-5.** Demo journeys have no "Handoff" — the demo IS the artifact. Full projects always end in Handoff (fixed 4 phases). The journey-tree adapts to both shapes.
-6. **The full-project journey includes Handoff.** Every full project's final milestone is literally named "Handoff" with 4 standard phases. The roadmapper enforces this.
-7. **Single approval gate.** One gate for the whole journey. Not per-milestone, not per-phase.
-8. **Milestone 1 is fully detailed (full projects).** M2..M{N-1} are sketched. Detail fills in when each milestone opens. Demos are always fully detailed because they're 1 milestone.
-9. **STATE.md through state.js.** Never edit STATE.md or tracking.json by hand.
-10. **Inline skill invocation.** When Step 0.5 offers `/qualia-map` or Step 1 invokes `/qualia-discuss`, invoke it inline — don't exit.
-11. **CONTEXT.md is mandatory.** Every project gets a domain glossary at `.planning/CONTEXT.md`. Seeded from the discovery interview answers. Loaded by every road agent. Kept terse.
-12. **ADRs are scarce.** `.planning/decisions/` exists from day one but only fills with hard-to-reverse, surprising-without-context, real-tradeoff decisions. Cargo-culting ADRs ruins the signal.
+1. **Project type is the first question, period.** Step 1 (Demo / Full / Quick) is the literal first interaction with the user — even before "what are you building". Every downstream step branches on the answer. Don't skip it, don't infer it, don't ask anything before it.
+2. **AskUserQuestion for every discrete-choice question.** Project type, brownfield gate, design vibe, client type, approval gate, auto-chain — all use the interactive UI. The ONLY free-text question in the kickoff flow is the Step 3 one-line pitch. No plain-text prompts for anything that has a closed set of answers.
+3. **No ad-hoc clarification questioning.** After Step 3 (one-line pitch), the next tool call is `/qualia-discuss`. No "let me ask a few quick things first", no "that's too broad, can you clarify". Depth is the discuss skill's job — not yours.
+4. **Discovery interview is mandatory.** Step 4 always invokes `/qualia-discuss` in PROJECT MODE. No free-form questioning loop, no "I'll just sketch PROJECT.md from the user's first message." The interview is 8 questions for demo, 14 for full project.
+5. **Research runs automatically.** No permission ask. Only `--quick` skips it. Demo path uses `<scope>quick</scope>` (3-call budget per researcher); full project uses standard 8-call budget.
+6. **Demo design philosophy is non-negotiable.** Real backend always (Supabase, real auth), DESIGN.md mandatory, slop-detect hard-block, 1 milestone, focus on real agent/platform functionality + design quality. No mock data, no lorem ipsum, no broken flows. Speed comes from skipping multi-milestone planning, never from skipping design quality, mocking the backend, or cutting corners on the core flow. A demo that uses mock data is not a Qualia demo.
+7. **Demos are 1 milestone, full projects are 2-5.** Demo journeys have no "Handoff" — the demo IS the artifact. Full projects always end in Handoff (fixed 4 phases). The journey-tree adapts to both shapes.
+8. **The full-project journey includes Handoff.** Every full project's final milestone is literally named "Handoff" with 4 standard phases. The roadmapper enforces this.
+9. **Single approval gate.** One gate for the whole journey. Not per-milestone, not per-phase.
+10. **Milestone 1 is fully detailed (full projects).** M2..M{N-1} are sketched. Detail fills in when each milestone opens. Demos are always fully detailed because they're 1 milestone.
+11. **STATE.md through state.js.** Never edit STATE.md or tracking.json by hand.
+12. **Inline skill invocation.** When Step 2 offers `/qualia-map` or Step 4 invokes `/qualia-discuss`, invoke it inline — don't exit.
+13. **CONTEXT.md is mandatory.** Every project gets a domain glossary at `.planning/CONTEXT.md`. Seeded from the discovery interview answers. Loaded by every road agent. Kept terse.
+14. **ADRs are scarce.** `.planning/decisions/` exists from day one but only fills with hard-to-reverse, surprising-without-context, real-tradeoff decisions. Cargo-culting ADRs ruins the signal.

package/skills/qualia-plan/SKILL.md

@@ -212,7 +212,7 @@ With `--gaps`, planner enters gap-closure mode:
 ## Rules
 
 1. **Plan-checker mandatory by default.** Skip only with `--skip-check`.
-2. **Max 3 revision cycles.** 3 fails → escalate; scope probably wrong.
+2. **Max 2 revision cycles.** 2 fails → escalate; scope probably wrong.
 3. **Honor locked decisions.** phase-{N}-context.md locked decisions non-negotiable.
 4. **One plan file per phase.** No phase-1-plan-v2.md. Edit in place.
 5. **Revision is surgical.** Fix only what checker flagged; no scope creep.

package/skills/qualia-polish/REFERENCE.md

@@ -256,10 +256,12 @@ Per the spec's hard constraint (§5g `prefers-reduced-motion` and §5c mobile-on
 
 This is intentional. Most visual regressions Fawzi has documented in `/insights` (hero videos cropped wrong on mobile, touch targets < 44px on mobile, navigation collapse misbehaving) only show up below 768. Scoring on desktop alone is how we got "looks great in dev" → "looks broken on the user's phone."
 
-## What the loop does NOT do (deferred to v5.2)
+## What the loop does NOT do
 
-- Cross-browser rendering checks (Firefox / WebKit) — Chromium-only, per `qualia-polish` Stage 4 precedent
-- Accessibility audits beyond what the rubric scores — use `/qualia-polish` Stage 3 (Lighthouse + axe) for that
-- Performance regressions — use `/qualia-polish --loop` only after Lighthouse score passes
-- Reference-image-only mode (compare to a target screenshot without a brief) — currently the brief is required; reference is supplemental
-- Multi-page sweeps — one URL per invocation; chain `/qualia-polish --loop` per route for site-wide passes
+- Cross-browser rendering checks (Firefox / WebKit) — Chromium-only, per `qualia-polish` Stage 4 precedent.
+- Accessibility audits beyond what the rubric scores — use `/qualia-polish` Stage 3 (Lighthouse + axe) for that.
+- Performance regressions — use `/qualia-polish --loop` only after Lighthouse score passes.
+- Reference-image-only mode (compare to a target screenshot without a brief) — the brief is required; reference is supplemental.
+- Aesthetic pivots — if the issue is "the whole vibe is wrong", `/qualia-vibe` swaps the aesthetic in minutes instead of grinding the loop against a vibe that doesn't fit.
+
+Implemented as of v5.2: `--routes a,b,c` for multi-route sweeps, `--reduced-motion` for `prefers-reduced-motion: reduce` capture.

package/skills/qualia-polish/SKILL.md

@@ -36,7 +36,7 @@ Other flags: `--register=brand|product` overrides register inference. Loop-speci
 
 When `--loop` is the first flag, the polish run is fully autonomous: screenshot a live URL at three viewports, score 8 design dimensions of `qualia-design/design-rubric.md` against the brief using vision, fix top issues in the codebase, re-screenshot, repeat until every dimension scores ≥ 3 or the kill-switch fires (regression, budget cap, max iterations).
 
-This is the surface formerly known as `/qualia-polish-loop` (consolidated into a flag in v5.8.0). The scripts ship at `skills/qualia-polish/scripts/{loop,playwright-capture,score}.mjs`; vision evaluator is `agents/visual-evaluator.md`; full loop spec lives in this skill's `REFERENCE.md`.
+Scripts ship at `skills/qualia-polish/scripts/{loop,playwright-capture,score}.mjs`; the vision evaluator is `agents/visual-evaluator.md`; the full loop spec lives in this skill's `REFERENCE.md`.
 
 When `--loop` is detected on entry, route to the loop process documented in `REFERENCE.md` and stop executing the standard stages below. The two paths share Stage 0 substrate gates and the rubric, but diverge from Stage 1 onward.
 
@@ -72,15 +72,17 @@ Read PRODUCT.md and DESIGN.md. Identify the **register** — Brand (marketing/la
 2. `register:` field in PRODUCT.md
 3. `--register` flag override
 
-For App / Redesign scope, write the brief BEFORE any code (use `ultrathink`):
+For App / Redesign scope, write the brief BEFORE any code (use `ultrathink`). Per `rules/one-opinion.md` — **propose one direction, do NOT list a menu of aesthetic options to the user.** Infer the one direction from `PRODUCT.md` register + anti-references + scene sentence, then commit to it in writing:
 
 ```
-Aesthetic direction:  {editorial · brutalist · luxury · maximalist · retro-futuristic · organic · terminal-native · ...}
-Color strategy:       {Restrained · Committed · Full palette · Drenched}
+Aesthetic direction:  {ONE concrete direction — e.g. "editorial broadsheet, ivory ground, deep navy ink, italic accents"}
+Color strategy:       {ONE choice — Restrained / Committed / Full palette / Drenched — with one-line justification}
 Scene sentence:       {who uses this, where, ambient light, mood — concrete}
 Differentiation:      {what someone remembers 24 hours later}
 ```
 
+If the user pushes back on the proposed direction, that is a `/qualia-vibe` trigger — switch surfaces, do not start enumerating alternatives in the brief.
+
 For Component / Section / Quick scope, the brief is implicit (loaded from DESIGN.md). Skip the ultrathink step but cite the relevant DESIGN.md tokens you'll touch.
 
 For Critique scope, no commit needed — you're scoring, not editing.
@@ -154,13 +156,13 @@ If a11y < 90 OR axe critical/serious violations: **fix programmatically** (th
 
 ### Stage 4 — Vision loop (Redesign scope only — max 2 iterations)
 
-Use Anthropic's `webapp-testing` skill (Playwright). Capture screenshots at 3 viewports: 375 / 768 / 1280. Single browser (Chromium) is fine in 2026 — cross-browser CSS rendering differences are vanishingly rare.
+Use `skills/qualia-polish/scripts/playwright-capture.mjs` (Playwright backend, with Chrome-binary fallback). Capture screenshots at 3 viewports: 375 / 768 / 1440 — these match what `agents/visual-evaluator.md` expects, and what the `--loop` mode captures. Single browser (Chromium) is fine in 2026 — cross-browser CSS rendering differences are vanishingly rare.
 
 ```
 viewports: [
   { width: 375,  height: 812,  name: 'mobile' },
   { width: 768,  height: 1024, name: 'tablet' },
-  { width: 1280, height: 800,  name: 'desktop' }
+  { width: 1440, height: 900,  name: 'desktop' }
 ]
 ```
 
@@ -261,7 +263,7 @@ node ~/.claude/bin/qualia-ui.js end "POLISHED" "{next command — depends on con
 | Symptom | Likely cause | Action |
 |---|---|---|
 | `bin/slop-detect.mjs not found` | Framework not installed in project | Run `npx qualia install` or pull script from framework repo |
-| `PRODUCT.md missing` | Pre-v4.5.0 project | Run setup (ask 5 questions, generate). For Component scope, can proceed with nudge. |
+| `PRODUCT.md missing` | Project predates the PRODUCT.md substrate | Run setup (ask 5 questions, generate). For Component scope, can proceed with nudge. |
 | `Lighthouse not installed` | Optional tool | Skip Stage 3 numeric gates, note in report. Don't fail. |
 | `webapp-testing skill not present` | Optional Anthropic skill | Skip Stage 4 vision loop on Redesign scope. Note in report. Recommend installing. |
 | Vision loop oscillates between iterations | Rubric not anchored properly | Verify rubric prompt instructs "default to 3, only 1-2 = fix". Hard cap at 2 iterations. |

package/skills/qualia-polish/scripts/loop.mjs

@@ -29,7 +29,7 @@
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
+import path, { dirname } from "node:path";
 import { argv, exit } from "node:process";
 import { spawnSync } from "node:child_process";
 
@@ -202,10 +202,17 @@ function cmdCommitFix() {
   if (!statePath || !file) { console.error("--state and --file required"); exit(2); }
   const state = loadState(statePath);
 
-  // slop-detect gate — block on critical findings
+  // slop-detect gate — block on critical findings. Resolve the script path with
+  // a search order so installs that put slop-detect in non-default locations
+  // still gate. Silent skip is reserved for genuinely missing installs.
   const slopBin = process.env.SLOP_DETECT_BIN || "node";
-  const slopScript = process.env.SLOP_DETECT_SCRIPT || `${process.env.HOME}/.claude/bin/slop-detect.mjs`;
-  if (existsSync(slopScript)) {
+  const slopCandidates = [
+    process.env.SLOP_DETECT_SCRIPT,
+    `${process.env.HOME}/.claude/bin/slop-detect.mjs`,
+    path.join(path.dirname(new URL(import.meta.url).pathname), "..", "..", "..", "bin", "slop-detect.mjs"),
+  ].filter(Boolean);
+  const slopScript = slopCandidates.find((p) => existsSync(p));
+  if (slopScript) {
     const r = spawnSync(slopBin, [slopScript, file], { encoding: "utf8" });
     if (r.status === 1) {
       console.log(JSON.stringify({ ok: false, gate: "slop-detect", file, output: r.stdout }, null, 2));
@@ -213,12 +220,17 @@ function cmdCommitFix() {
     }
   }
 
-  // Stage + commit
+  // Stage + commit. Set a bot identity inline so the commit works on fresh
+  // clones where git user.name / user.email aren't configured yet.
   const safeSlug = String(slug).toLowerCase().replace(/[^a-z0-9-]+/g, "-").slice(0, 48);
   const msg = `qpl-${state.iteration}: ${safeSlug}`;
   const add = spawnSync("git", ["add", file], { encoding: "utf8" });
   if (add.status !== 0) { console.error(add.stderr); exit(2); }
-  const commit = spawnSync("git", ["commit", "-m", msg], { encoding: "utf8" });
+  const commit = spawnSync("git", [
+    "-c", "user.name=Qualia Polish Loop",
+    "-c", "user.email=polish-loop@qualia.solutions",
+    "commit", "-m", msg,
+  ], { encoding: "utf8" });
   if (commit.status !== 0) {
     // empty diff → nothing to commit; not fatal
     if (/nothing to commit/i.test(commit.stdout + commit.stderr)) {

package/skills/qualia-postmortem/SKILL.md

@@ -95,7 +95,7 @@ matches the failure. Use this lookup:
 | Wave 2 task ran before wave 1 committed | `agents/planner.md` (dependency graph) |
 | Build passed locally, broke in CI | `rules/deployment.md` or a missing pre-deploy-gate scan |
 | RLS missing on new table | `rules/security.md` + `agents/builder.md` (security persona handling) |
-| Design regression — fonts off, contrast fail | `qualia-design/frontend.md` + `skills/qualia-design/SKILL.md` |
+| Design regression — fonts off, contrast fail | `qualia-design/frontend.md` + `qualia-design/design-laws.md` + `skills/qualia-polish/SKILL.md` |
 | Migration unsafe (DROP without IF EXISTS, etc.) | `hooks/migration-guard.js` |
 | Verifier missed it | `agents/verifier.md` — most embarrassing case, address with extra care |
 

package/skills/qualia-report/SKILL.md

@@ -221,7 +221,8 @@ PAYLOAD=$(
       tasks_done:t.tasks_done||0,tasks_total:t.tasks_total||0,verification:t.verification||'pending',
       gap_cycles:(t.gap_cycles||{})[String(t.phase)]||0,build_count:t.build_count||0,
       deploy_count:t.deploy_count||0,deployed_url:t.deployed_url||'',
-      session_started_at:t.session_started_at||'',last_pushed_at:t.last_pushed_at||'',
+      ...(t.session_started_at?{session_started_at:t.session_started_at}:{}),
+      ...(t.last_pushed_at?{last_pushed_at:t.last_pushed_at}:{}),
       session_duration_minutes:sessionDurationMinutes,
       lifetime:t.lifetime||{},commits:commits,notes:notes,
       submitted_by:process.env.SUBMITTED_BY||'unknown',submitted_at:process.env.SUBMITTED_AT

package/skills/qualia-road/SKILL.md

@@ -32,7 +32,7 @@ Final milestone = Handoff:
 Done.
 ```
 
-## Design as a thread (v4.5.0+)
+## Design as a thread
 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 scope-adaptive
@@ -45,7 +45,19 @@ Every road agent loads `PRODUCT.md + DESIGN.md + design-laws.md` substrate. Buil
 /qualia-polish --quick                       ~1m  gates only
 ```
 
-## /qualia-polish --loop -- autonomous visual QA (v5.1+, consolidated into /qualia-polish in v5.8)
+## Design pivots — /qualia-vibe (v6.1+)
+```
+/qualia-vibe                              fast aesthetic pivot: ONE proposed direction, swap tokens, keep layout (~3 min)
+/qualia-vibe brutalist                    explicit pivot to named direction
+/qualia-vibe --variants 3                 opt-in menu (uses AskUserQuestion; default flow is one-opinion)
+/qualia-vibe --extract https://stripe.com reverse-engineer DESIGN.md from a reference URL
+/qualia-vibe --extract ./inspo.png        same, from a local screenshot
+/qualia-vibe --sync                       show drift between code (CSS vars, Tailwind config) and DESIGN.md
+/qualia-vibe --sync --write               patch DESIGN.md to match code, commit
+```
+`/qualia-vibe` is for the WHOLE-SITE aesthetic. For surgical component-level fixes use `/qualia-polish` (component or section scope). For ground-up structural redesign use `/qualia-polish --redesign`.
+
+## /qualia-polish --loop — autonomous visual QA
 ```
 /qualia-polish --loop http://localhost:3000               screenshot + eval + fix loop
 /qualia-polish --loop {url} --max 4                       cap iterations
@@ -55,14 +67,14 @@ Every road agent loads `PRODUCT.md + DESIGN.md + design-laws.md` substrate. Buil
 ```
 Screenshots at 3 viewports (375/768/1440), scores 8 design dimensions using vision, fixes issues, re-screenshots, loops until all dims >= 3 or kill-switch triggers. Per-iteration git commits for clean revert.
 
-## v5.3+ skills
+## Deterministic-enforcement skills
 ```
 /qualia-hook-gen       convert a CLAUDE.md/rules instruction into a deterministic pre-tool-use hook
 /qualia-optimize --deepen   spawns 3 parallel interface-design variants per candidate (Step 5b)
 ```
 `/qualia-hook-gen` reduces lifetime token cost (each migrated rule frees ~50-200 tokens per request). `/qualia-optimize --deepen` produces dramatically better refactor RFCs because 3 radically-different interfaces are surfaced and the human picks/hybridizes.
 
-## Alignment substrate (v5.0+)
+## Alignment substrate
 Before high-stakes phases, run alignment skills against `.planning/CONTEXT.md` (domain glossary) and `.planning/decisions/` (ADRs):
 
 ```

package/skills/qualia-verify/SKILL.md

@@ -19,7 +19,7 @@ Spawn verifier to check phase goal. Does NOT trust build summaries; greps codeba
 `/qualia-verify` — verify current built phase
 `/qualia-verify {N}` — verify specific phase
 `/qualia-verify {N} --auto` — verify + auto-chain: PASS → next phase/milestone; FAIL → gap closure; gap limit → halt
-`/qualia-verify {N} --adversarial` — second verifier in fresh context with adversarial prompt. Union findings. Recommended for high-stakes phases (Handoff, payment/auth/migration). v4.3.0+.
+`/qualia-verify {N} --adversarial` — second verifier in fresh context with adversarial prompt. Union findings. Recommended for high-stakes phases (Handoff, payment/auth/migration).
 
 ## Process
 
@@ -142,7 +142,7 @@ Per gap:
 node ~/.claude/bin/qualia-ui.js fail "{gap description}"
 ```
 
-**Self-healing (v4.3.0+):** before re-planning gaps, run postmortem so framework learns from miss. Writes `.planning/phase-{N}-postmortem.md`. Does NOT auto-apply deltas unless user runs `/qualia-postmortem --apply`.
+**Self-healing:** before re-planning gaps, run postmortem so the framework learns from the miss. Writes `.planning/phase-{N}-postmortem.md`. Does NOT auto-apply deltas unless user runs `/qualia-postmortem --apply`.
 
 ```
 /qualia-postmortem --phase {N}