qualia-framework 6.2.7 → 6.2.10

package/skills/qualia-new/SKILL.md

@@ -43,7 +43,7 @@ Initialize a project with the **entire arc mapped from kickoff to handoff**. All
 ### Step 0. Banner
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner new
+node ${QUALIA_BIN}/qualia-ui.js banner new
 ```
 
 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.
@@ -122,7 +122,7 @@ If "More questions": re-invoke `/qualia-discuss` for additional rounds. Otherwis
 
 ### 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 13.
+From questioning answers, infer type → `website` | `ai-agent` | `voice-agent` | `mobile-app` | `null`. If matched, `cat ${QUALIA_TEMPLATES}/projects/{type}.md` gives suggested milestone arc. Store `template_type` for Step 13.
 
 ### Step 6. Design Direction (frontend only)
 
@@ -140,7 +140,7 @@ Plus free-text: "Any brand colors or reference sites I should look at?"
 
 If client, ask name. Check saved prefs:
 ```bash
-node ~/.claude/bin/knowledge.js search "{client name}"
+node ${QUALIA_BIN}/knowledge.js search "{client name}"
 ```
 
 ### Step 8. Write PROJECT.md
@@ -159,11 +159,11 @@ The domain glossary is the single highest-leverage piece of substrate — every
 
 ```bash
 # Copy template
-cp ~/.claude/qualia-templates/CONTEXT.md .planning/CONTEXT.md
+cp ${QUALIA_TEMPLATES}/CONTEXT.md .planning/CONTEXT.md
 
 # Initialize ADR folder with the template available for reference
 mkdir -p .planning/decisions
-cp ~/.claude/qualia-templates/decisions/ADR-template.md .planning/decisions/_template.md
+cp ${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 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:
@@ -252,7 +252,7 @@ git commit -m "docs: DESIGN.md — direction commit + OKLCH palette + tokens"
 Only `/qualia-new --quick` skips this step.
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner research
+node ${QUALIA_BIN}/qualia-ui.js banner research
 mkdir -p .planning/research
 ```
 
@@ -275,7 +275,7 @@ git commit -m "docs: research synthesis (4 dimensions, multi-milestone scope)"
 
 Show key findings:
 ```bash
-node ~/.claude/bin/qualia-ui.js ok "Research complete"
+node ${QUALIA_BIN}/qualia-ui.js ok "Research complete"
 ```
 Display top 3 from SUMMARY.md (stack recommendation, table stakes, top pitfall).
 
@@ -300,7 +300,7 @@ Gather any additional requirements the user wants that research missed.
 ### Step 13. Run Roadmapper
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner roadmap
+node ${QUALIA_BIN}/qualia-ui.js banner roadmap
 ```
 
 **Roadmapper output branches on `PROJECT_TYPE`:**
@@ -315,7 +315,7 @@ Spawn the roadmapper with `<project_type>$PROJECT_TYPE</project_type>` in the pr
 Render the branded journey ladder:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js journey-tree .planning/JOURNEY.md
+node ${QUALIA_BIN}/qualia-ui.js journey-tree .planning/JOURNEY.md
 ```
 
 This shows M1..M{N} as a vertical ladder: shipped milestones get a green dot, current gets a teal diamond with `[CURRENT]` tag, future get dim open circles. Handoff gets `[FINAL]` tag. Why-now + phase sketch render under current and final.
@@ -345,9 +345,9 @@ git commit -m "docs: journey + requirements + milestone 1 roadmap ({N} milestone
 **After approval, show the progressive-detail reminder explicitly:**
 
 ```bash
-node ~/.claude/bin/qualia-ui.js info "Milestone 1 is fully planned now."
-node ~/.claude/bin/qualia-ui.js info "Milestones 2..{N-1} are sketched (names + one-line goals)."
-node ~/.claude/bin/qualia-ui.js info "Full phase detail for each later milestone gets written when /qualia-milestone opens it."
+node ${QUALIA_BIN}/qualia-ui.js info "Milestone 1 is fully planned now."
+node ${QUALIA_BIN}/qualia-ui.js info "Milestones 2..{N-1} are sketched (names + one-line goals)."
+node ${QUALIA_BIN}/qualia-ui.js info "Full phase detail for each later milestone gets written when /qualia-milestone opens it."
 ```
 
 (Skip this block when `--full-detail` was used — all milestones are already fully planned in that case.)
@@ -368,7 +368,7 @@ git commit -m "chore: environment setup" 2>/dev/null
 If invoked with `--auto`, skip straight into building Milestone 1:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js info "Auto mode — chaining into /qualia-plan 1"
+node ${QUALIA_BIN}/qualia-ui.js info "Auto mode — chaining into /qualia-plan 1"
 ```
 
 Then inline-invoke `/qualia-plan 1`. That skill will chain into `/qualia-build 1 → /qualia-verify 1 → /qualia-plan 2 → ...` until Milestone 1's last phase verifies, at which point the chain pauses at the milestone boundary and asks:
@@ -380,7 +380,7 @@ Then inline-invoke `/qualia-plan 1`. That skill will chain into `/qualia-build 1
 **Without `--auto`**, end with a clear pointer:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "JOURNEY READY" "/qualia-plan 1"
+node ${QUALIA_BIN}/qualia-ui.js end "JOURNEY READY" "/qualia-plan 1"
 ```
 
 Show summary:

package/skills/qualia-optimize/REFERENCE.md

@@ -258,7 +258,7 @@ Constraints:
 )
 ```
 
-After all 3 return, present a comparison table to the user (see SKILL.md Step 5b). User picks 1, 2, 3, or hybrid. Then a single synthesizer agent writes the Refactor RFC to `.planning/REFACTOR-{slug}.md` honoring the user's pick.
+After all 3 return, present a comparison table to the user (see SKILL.md Step 5b). User picks 1, 2, 3, or hybrid. Then a single synthesizer agent writes the Refactor RFC to `.planning/reports/refactor/REFACTOR-{slug}.md` honoring the user's pick.
 
 **Token cost**: ~6K per variant × 3 variants = ~18K for the fan-out. Cached prefix (CONTEXT.md + ADRs + candidate block) is shared across the 3 spawns, so effective cost is closer to ~12K. The output rfc-pick stage adds ~3K. Total per-deepening-candidate: ~15K — well within Qualia's per-skill budget.
 

package/skills/qualia-optimize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-optimize
-description: "Deep optimization pass — reads .planning/ AND codebase to find performance, design, UI, backend, frontend, AND architecture-deepening opportunities. Spawns parallel specialist agents. Use whenever the user says 'optimize', 'optimization pass', 'find issues', 'qualia-optimize', 'deep optimize', 'performance audit', 'design alignment check', 'speed up', 'slow', 'bundle size', 'refactor architecture', 'shallow modules', 'simplify', or wants a comprehensive quality sweep. Supports --perf, --ui, --backend, --alignment, --deepen, --fix flags."
+description: "Deep improvement discovery pass — reads .planning/ AND codebase to find performance, design, UI, backend, frontend, alignment, and architecture-deepening opportunities. Spawns parallel specialist agents and writes OPTIMIZE.md/RFCs; practical repair work routes to /qualia-fix or /qualia-polish. Use when the user says 'optimize', 'optimization pass', 'find issues', 'deep improve', 'performance audit', 'design alignment check', 'speed up', 'bundle size', 'refactor architecture', 'shallow modules', 'simplify', or wants a comprehensive quality sweep. Supports --perf, --ui, --backend, --alignment, --deepen, --fix flags."
 allowed-tools:
   - Bash
   - Read
@@ -21,6 +21,8 @@ Detailed agent-prompt templates live in `REFERENCE.md` (in this same skill folde
 
 Reads `.planning/` docs AND codebase. Never analyze one without the other.
 
+Optimize is discovery-first, not a hotfix lane. If the user has one broken behavior, route to `/qualia-fix`. If the user has visual quality problems, route to `/qualia-polish`. Use optimize when the question is "where can this system get better?"
+
 ## Usage
 
 - `/qualia-optimize` — Full (all 7 dimensions + architecture deepening)
@@ -29,7 +31,7 @@ Reads `.planning/` docs AND codebase. Never analyze one without the other.
 - `/qualia-optimize --backend` — Backend only (RLS, auth, queries, edge fns)
 - `/qualia-optimize --alignment` — Planning-code alignment only
 - `/qualia-optimize --deepen` — Architecture deepening only (Ousterhout: shallow modules, deeper interfaces)
-- `/qualia-optimize --fix` — Auto-fix LOW/MEDIUM from existing OPTIMIZE.md
+- `/qualia-optimize --fix` — Compatibility mode: convert LOW/MEDIUM `.planning/reports/optimize/OPTIMIZE.md` findings into safe repairs, using `/qualia-fix` rules for any code mutation
 
 ## Process
 
@@ -37,7 +39,7 @@ Reads `.planning/` docs AND codebase. Never analyze one without the other.
 
 Mode from $ARGUMENTS. Default: `full`.
 Modes: `full`, `perf`, `ui`, `backend`, `alignment`, `deepen`, `fix`.
-`--fix` skips to Step 9 (requires `.planning/OPTIMIZE.md`).
+`--fix` skips to Step 9 (requires `.planning/reports/optimize/OPTIMIZE.md`, with fallback to legacy `.planning/OPTIMIZE.md`) and follows `/qualia-fix` mutation rules.
 
 ### Step 2: Load Planning Context (MANDATORY)
 
@@ -73,8 +75,8 @@ ls .planning/decisions/ 2>/dev/null && cat .planning/decisions/*.md 2>/dev/null
 
 Also read rules:
 ```bash
-cat ~/.claude/qualia-design/frontend.md 2>/dev/null
-cat ~/.claude/rules/security.md 2>/dev/null
+cat ${QUALIA_DESIGN}/frontend.md 2>/dev/null
+cat ${QUALIA_RULES}/security.md 2>/dev/null
 ```
 
 Store all; inline into agent prompts.
@@ -146,7 +148,7 @@ Collect all 3 proposals. Present to the user as a side-by-side table:
 | 2 | ... | ... | ... | ... |
 | 3 | ... | ... | ... | ... |
 
-User picks `1`, `2`, `3`, or `hybrid` (with notes on which elements from which proposals to combine). The synthesizer then writes a "Refactor RFC" to `.planning/REFACTOR-{slug}.md` and optionally opens a GH issue.
+User picks `1`, `2`, `3`, or `hybrid` (with notes on which elements from which proposals to combine). The synthesizer then writes a "Refactor RFC" to `.planning/reports/refactor/REFACTOR-{slug}.md` and optionally opens a GH issue.
 
 **Why parallel + radically different**: a single deepening proposal anchors on the first idea the LLM has. Three parallel proposals with diverse design constraints surface trade-offs the user can see at a glance — and the human's "taste" dominates the choice rather than the agent's first instinct. Empirically (Matt Pocock + Qualia internal testing) this produces dramatically better refactor RFCs than a single-pass proposal.
 
@@ -187,7 +189,11 @@ All agents done:
 
 ### Step 8: Write OPTIMIZE.md and Present Results
 
-Write to `.planning/OPTIMIZE.md`:
+Create the report directory and write to `.planning/reports/optimize/OPTIMIZE.md`:
+
+```bash
+mkdir -p .planning/reports/optimize
+```
 
 ```markdown
 ---
@@ -237,7 +243,7 @@ status: {clean|needs_attention|critical_issues}
 
 Commit:
 ```bash
-git add .planning/OPTIMIZE.md && git commit -m "docs: optimization report ({mode} mode, {critical} critical)"
+git add .planning/reports/optimize/OPTIMIZE.md && git commit -m "docs: optimization report ({mode} mode, {critical} critical)"
 ```
 
 **Present results:**
@@ -247,25 +253,26 @@ If CRITICAL findings exist:
 {critical} critical issues found. Options:
 
 1. Create a fix phase in ROADMAP.md for critical + high findings
-2. Auto-fix LOW/MEDIUM findings: /qualia-optimize --fix
-3. Review full report: cat .planning/OPTIMIZE.md
+2. Repair a specific blocker: /qualia-fix {finding}
+3. Convert LOW/MEDIUM findings into safe repairs: /qualia-optimize --fix
+4. Review full report: cat .planning/reports/optimize/OPTIMIZE.md
 ```
 
 If no CRITICAL:
 ```
 Optimization complete. {total} findings ({high} high, {medium} medium, {low} low).
-Report: .planning/OPTIMIZE.md
+Report: .planning/reports/optimize/OPTIMIZE.md
 
-Run /qualia-optimize --fix to auto-fix LOW/MEDIUM findings.
+Run /qualia-fix for a specific defect, or /qualia-optimize --fix only for safe LOW/MEDIUM cleanup from this report.
 ```
 
 ### Step 9: --fix Mode
 
-`--fix` mode:
+`--fix` mode is a compatibility cleanup lane, not a replacement for `/qualia-fix`.
 
-1. Read `.planning/OPTIMIZE.md`; missing: "Run /qualia-optimize first"
+1. Read `.planning/reports/optimize/OPTIMIZE.md` (fallback: `.planning/OPTIMIZE.md` for older projects); missing: "Run /qualia-optimize first"
 2. Filter to LOW + MEDIUM only
-3. Per finding with clear, safe fix:
+3. Per finding with clear, safe fix, apply `/qualia-fix` mutation rules:
    - Read target file
    - Apply fix
    - Verify (npx tsc --noEmit if TS)
@@ -273,7 +280,7 @@ Run /qualia-optimize --fix to auto-fix LOW/MEDIUM findings.
 5. Commit
 6. Report fixed vs remaining
 
-**Never auto-fix CRITICAL/HIGH.** Require human judgment.
+**Never auto-fix CRITICAL/HIGH.** Require human judgment. If a finding is an actual broken behavior, use `/qualia-fix {finding}` instead of burying it in optimize.
 
 ### Step 10: Gap Phase Creation (user picks option 1)
 

package/skills/qualia-pause/SKILL.md

@@ -15,7 +15,7 @@ Save context so the next session picks up where you left off.
 ## Process
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner pause
+node ${QUALIA_BIN}/qualia-ui.js banner pause
 ```
 
 ### 1. Read State
@@ -63,6 +63,6 @@ git commit -m "WIP: {phase name} — session handoff"
 ```
 
 ```bash
-node ~/.claude/bin/state.js transition --to note --notes "Session paused — see .continue-here.md"
+node ${QUALIA_BIN}/state.js transition --to note --notes "Session paused — see .continue-here.md"
 ```
 Do NOT manually edit STATE.md or tracking.json — state.js handles both.

package/skills/qualia-plan/SKILL.md

@@ -27,15 +27,19 @@ Spawn planner to break phase into tasks, validate with checker (max 2 revision c
 
 ## Process
 
+### 0. Codex goal (Codex runtime only)
+
+Per `rules/codex-goal.md` — set the thread goal at plan start with scope `phase`. The objective covers both planning and the subsequent build, so a single goal-set at this stage is enough.
+
 ### 1. Determine Phase & Load Context
 
 ```bash
 cat .planning/STATE.md 2>/dev/null
 cat .planning/ROADMAP.md 2>/dev/null
 cat .planning/PROJECT.md 2>/dev/null
-node ~/.claude/bin/knowledge.js
-node ~/.claude/bin/knowledge.js load patterns
-node ~/.claude/bin/knowledge.js load client
+node ${QUALIA_BIN}/knowledge.js
+node ${QUALIA_BIN}/knowledge.js load patterns
+node ${QUALIA_BIN}/knowledge.js load client
 ```
 
 No phase number → current phase from STATE.md.
@@ -63,13 +67,13 @@ Suggest: *"Run /qualia-discuss {N} first to lock decisions? Optional."*
 ### 3. Spawn Planner (Fresh Context)
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner plan {N} "{phase name from ROADMAP.md}"
-node ~/.claude/bin/qualia-ui.js spawn planner "Breaking phase into tasks..."
+node ${QUALIA_BIN}/qualia-ui.js banner plan {N} "{phase name from ROADMAP.md}"
+node ${QUALIA_BIN}/qualia-ui.js spawn planner "Breaking phase into tasks..."
 ```
 
 ```
 Agent(prompt="
-Role: @~/.claude/agents/planner.md
+Role: @${QUALIA_AGENTS}/planner.md
 
 <project_context>
 @.planning/PROJECT.md
@@ -112,7 +116,7 @@ Read generated plan. Spawn checker:
 
 ```
 Agent(prompt="
-Role: @~/.claude/agents/plan-checker.md
+Role: @${QUALIA_AGENTS}/plan-checker.md
 
 <plan_path>.planning/phase-{N}-plan.md</plan_path>
 <phase_goal>{goal from ROADMAP.md}</phase_goal>
@@ -134,7 +138,7 @@ Per revision:
 
 ```
 Agent(prompt="
-Role: @~/.claude/agents/planner.md
+Role: @${QUALIA_AGENTS}/planner.md
 
 <revision_mode>true</revision_mode>
 <current_plan>@.planning/phase-{N}-plan.md</current_plan>
@@ -151,7 +155,7 @@ After revision, re-spawn checker. Max 2 total cycles.
 **BLOCKED after 2 cycles:**
 
 ```bash
-node ~/.claude/bin/qualia-ui.js fail "Plan failed validation after 2 revisions"
+node ${QUALIA_BIN}/qualia-ui.js fail "Plan failed validation after 2 revisions"
 ```
 
 Show remaining issues. Options:
@@ -161,10 +165,19 @@ Show remaining issues. Options:
 
 ### 5. Present Final Plan
 
+Before presenting, write the machine-readable contract:
+
+```bash
+node ${QUALIA_BIN}/plan-contract.js validate .planning/phase-{N}-contract.json
+node ${QUALIA_BIN}/state.js validate-plan --phase {N} --require-contract
+```
+
+The planner must create `.planning/phase-{N}-contract.json` from the final plan. This JSON contract is the authority for build and verification; Markdown contracts are explanatory only. If validation fails, revise the plan/contract pair before asking for approval.
+
 Render story-file dashboard:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js plan-summary .planning/phase-{N}-plan.md
+node ${QUALIA_BIN}/qualia-ui.js plan-summary .planning/phase-{N}-plan.md
 ```
 
 End with plain text: *"Approve? (yes / adjust)"*
@@ -174,7 +187,8 @@ If "adjust" — get feedback, re-spawn planner with revision context, re-validat
 ### 6. Update State
 
 ```bash
-node ~/.claude/bin/state.js transition --to planned --phase {N}
+node ${QUALIA_BIN}/state.js validate-plan --phase {N} --require-contract
+node ${QUALIA_BIN}/state.js transition --to planned --phase {N}
 ```
 
 Error → show, stop. Do NOT edit STATE.md or tracking.json manually.
@@ -184,7 +198,7 @@ Error → show, stop. Do NOT edit STATE.md or tracking.json manually.
 **`--auto`:** invoke `/qualia-build {N} --auto` inline. User approved at `/qualia-new`; no per-phase gate.
 
 ```bash
-node ~/.claude/bin/qualia-ui.js info "Auto mode — chaining into /qualia-build {N}"
+node ${QUALIA_BIN}/qualia-ui.js info "Auto mode — chaining into /qualia-build {N}"
 ```
 
 Then invoke `qualia-build` inline with `--auto`.
@@ -192,7 +206,7 @@ Then invoke `qualia-build` inline with `--auto`.
 **Guided mode:** stop, show next step:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "PHASE {N} PLANNED" "/qualia-build {N}"
+node ${QUALIA_BIN}/qualia-ui.js end "PHASE {N} PLANNED" "/qualia-build {N}"
 ```
 
 ## Gap Closure Mode (`--gaps`)

package/skills/qualia-polish/REFERENCE.md

@@ -55,10 +55,10 @@ Agent({
   subagent_type: "qualia-visual-evaluator",
   description: "Score iteration {N} screenshots against rubric",
   prompt: `
-Role: @~/.claude/agents/visual-evaluator.md
+Role: @${QUALIA_AGENTS}/visual-evaluator.md
 
 <rubric>
-{INLINE qualia-design/design-rubric.md §"The 8 dimensions" through §"Aggregate score"}
+{INLINE qualia-design/design-rubric.md §"The 9 dimensions" through §"Aggregate score"}
 </rubric>
 
 <brief>
@@ -101,7 +101,7 @@ Agent({
   subagent_type: "qualia-builder",
   description: "Fix {dim} issue: {short description}",
   prompt: `
-Role: @~/.claude/agents/builder.md
+Role: @${QUALIA_AGENTS}/builder.md
 
 <phase_context>
 You are inside /qualia-polish --loop iteration {N}. The vision evaluator scored
@@ -133,7 +133,7 @@ the {dim} dimension at {score}. Your single task: fix that one dimension.
 2. Make the MINIMUM edit to fix this one dimension. Do not refactor. Do not change logic. Do not touch state management. Do not change copy unless this is a microcopy issue.
 3. Use design tokens from DESIGN.md. Do not invent new color values, font names, or spacing.
 4. After the edit, commit via the orchestrator (slop-detect-gated):
-     node ~/.claude/skills/qualia-polish/scripts/loop.mjs commit-fix --state {STATE} --file {file} --slug {dim}-{short-keyword}
+     node ${QUALIA_SKILLS}/qualia-polish/scripts/loop.mjs commit-fix --state {STATE} --file {file} --slug {dim}-{short-keyword}
    If slop-detect blocks (exit 2), READ the slop output and re-edit. If you cannot fix without violating slop-detect, return BLOCKED with the conflict.
 5. Return DONE with: file modified, lines changed, slop-detect: pass, commit: {sha}.
 </task>
@@ -153,10 +153,10 @@ the {dim} dimension at {score}. Your single task: fix that one dimension.
 ```json
 {
   "iteration": 1,
-  "scores": { "typography": 1, "color": 1, "spatial": 3, "layout": 1, "shadow": 3, "motion": 3, "microcopy": 1, "container": 1 },
-  "aggregate": 14,
+  "scores": { "typography": 1, "color": 1, "spatial": 3, "layout": 1, "shadow": 3, "motion": 3, "microcopy": 1, "container": 1, "graphics": 1 },
+  "aggregate": 15,
   "pass": false,
-  "failing_dims": ["typography", "color", "layout", "microcopy", "container"],
+  "failing_dims": ["typography", "color", "layout", "microcopy", "container", "graphics"],
   "top_issues": [
     { "dim": "color", "severity": "critical", "description": "blue→purple gradient on hero", "likely_file": "src/styles/globals.css", "fix": "replace linear-gradient with single accent var(--accent)" },
     { "dim": "typography", "severity": "critical", "description": "Inter as primary font-family", "likely_file": "src/styles/globals.css", "fix": "swap to Fraunces + JetBrains Mono per DESIGN.md §3" },
@@ -222,23 +222,23 @@ The pilot-results doc at `docs/playwright-loop-pilot-results.md` records the act
 ## Iteration log
 
 ### Iteration 1
-- Scores: typo=1 colo=1 spat=3 layo=1 shad=3 moti=3 micr=1 cont=1
-- Aggregate: 14/40 (avg 1.75)
-- Pass: NO (failing: typography, color, layout, microcopy, container)
+- Scores: typo=1 colo=1 spat=3 layo=1 shad=3 moti=3 micr=1 cont=1 grap=1
+- Aggregate: 15/45 (avg 1.67)
+- Pass: NO (failing: typography, color, layout, microcopy, container, graphics)
 - Top issues:
   - **color** [critical] blue→purple gradient on hero → src/styles/globals.css
   - **typography** [critical] Inter as primary → src/styles/globals.css
   - **layout** [high] three identical cards → src/pages/index.tsx
 
 ### Iteration 2
-- Scores: typo=3 colo=3 spat=3 layo=2 shad=3 moti=3 micr=2 cont=2
-- Aggregate: 21/40 (avg 2.62)
+- Scores: typo=3 colo=3 spat=3 layo=2 shad=3 moti=3 micr=2 cont=2 grap=2
+- Aggregate: 23/45 (avg 2.56)
 - Pass: NO (failing: layout, microcopy, container)
 - ...
 
 ### Iteration 3
-- Scores: typo=4 colo=3 spat=3 layo=3 shad=3 moti=3 micr=3 cont=3
-- Aggregate: 25/40 (avg 3.13)
+- Scores: typo=4 colo=3 spat=3 layo=3 shad=3 moti=3 micr=3 cont=3 grap=4
+- Aggregate: 29/45 (avg 3.22)
 - Pass: YES
 
 ## Fix commits (revertable)

package/skills/qualia-polish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-polish
-description: "Scope-adaptive design pass. Works on a single component, a route, the whole app, a ground-up redesign, or an autonomous visual loop. Trigger on 'polish', 'design pass', 'fix the design', 'redesign', 'critique', 'audit design', 'looks ugly', 'make it look better', 'polish loop', 'visual loop', 'fix what I see', 'iterate on the design until it's correct'. Replaces /qualia-polish-loop (now /qualia-polish --loop) and /qualia-design from earlier versions."
+description: "Scope-adaptive visual quality pass. Works on a single component, a route, the whole app, a ground-up redesign, or an autonomous visual loop, but does not repair business logic or broken data flow. Trigger on 'polish', 'design pass', 'fix the design', 'redesign', 'critique', 'audit design', 'looks ugly', 'make it look better', 'polish loop', 'visual loop', 'fix what I see', 'iterate on the design until it's correct'. Route functional bugs to /qualia-fix and aesthetic token pivots to /qualia-vibe."
 allowed-tools:
   - Bash
   - Read
@@ -9,12 +9,16 @@ allowed-tools:
   - Grep
   - Glob
   - Agent
+  - WebSearch
+  - WebFetch
 argument-hint: "[file|route|--redesign|--critique|--quick|--loop] [--register=brand|product] [--brief PATH] [--max 8] [--viewports 375,768,1440]"
 ---
 
 # /qualia-polish — Scope-Adaptive Design Pass
 
-One command. Seven scopes. Use it whenever you need design work, from a 30-second component touch-up to a 30-minute ground-up redesign to a fully autonomous see-fix-verify loop.
+One command. Seven scopes. Use it whenever you need design work, from a 30-second component touch-up to a ground-up redesign with current design research, complex visuals, and a fully transparent see-fix-verify loop.
+
+Polish fixes visual quality only. Broken behavior, failing tests, API bugs, state bugs, and config errors go to `/qualia-fix`. Whole-site aesthetic token pivots go to `/qualia-vibe`.
 
 ## Scopes
 
@@ -32,9 +36,23 @@ The first argument selects the scope. Stage selection follows from scope.
 
 Other flags: `--register=brand|product` overrides register inference. Loop-specific flags: `--brief PATH`, `--max N`, `--viewports 375,768,1440`, `--ref PATH`, `--budget 100000`.
 
+## Transparent Command Output
+
+Follow `rules/command-output.md`. At minimum, show:
+
+```text
+Command: /qualia-polish {scope}
+Scope: {target files/routes}
+Intent: visual quality | redesign | critique | loop
+Mutation: none | planned | active | blocked
+Evidence: DESIGN.md, PRODUCT.md, qualia-design files, screenshots, online sources when used
+Output: changed files, screenshots, report, commit
+Next: {next command or done}
+```
+
 ## --loop mode (autonomous visual loop)
 
-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).
+When `--loop` is the first flag, the polish run is fully autonomous: screenshot a live URL at three viewports, score 9 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).
 
 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`.
 
@@ -46,7 +64,7 @@ Before any work — design or otherwise — pass these gates. Skipping them prod
 
 | Gate | Required check | If fail |
 |---|---|---|
-| Substrate | `qualia-design/design-laws.md`, `design-brand.md`, `design-product.md`, `design-rubric.md` exist and have been read | Read them. |
+| Substrate | `qualia-design/design-laws.md`, `design-brand.md`, `design-product.md`, `design-rubric.md`, `design-reference.md`, `frontend.md`, `graphics.md` exist and have been read when scope requires them | Read them. |
 | PRODUCT | `PRODUCT.md` exists at project root, has `register:` field, and is not placeholder (`[TODO]` markers, < 200 chars) | Run setup: ask 5 questions and generate it. Never synthesize from prompt alone. |
 | DESIGN | `DESIGN.md` exists. If missing on App / Redesign scope, BLOCK and run setup. If missing on Component / Section / Critique / Quick scope, NUDGE and proceed. | Generate from PRODUCT.md + 3 questions. |
 | Slop-detect | `bin/slop-detect.mjs` is callable | Install or pull from framework. |
@@ -55,13 +73,13 @@ Before any work — design or otherwise — pass these gates. Skipping them prod
 State this preflight explicitly before editing:
 
 ```
-POLISH_PREFLIGHT: substrate=pass product=pass design=pass|nudged slop_detect=pass mutation=open
+POLISH_PREFLIGHT: substrate=pass product=pass design=pass|nudged graphics=loaded|skipped slop_detect=pass mutation=open
 ```
 
 ## Process
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner polish
+node ${QUALIA_BIN}/qualia-ui.js banner polish
 ```
 
 ### Stage 0 — Direction commit (mandatory; light on small scopes)
@@ -79,8 +97,18 @@ Aesthetic direction:  {ONE concrete direction — e.g. "editorial broadsheet, iv
 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}
+Complex visual:       {hero/product/data/diagram/3D/canvas concept, or "none because..."}
+Research anchors:     {2-4 sources checked, or "local only" for component/quick}
 ```
 
+For Redesign scope, run a short online best-practices check before the brief unless the user explicitly says offline. Prefer primary sources:
+- W3C WCAG 2.2 / WAI for accessibility, focus, target size, contrast: https://www.w3.org/TR/WCAG22/
+- Apple Human Interface Guidelines for motion/accessibility restraint: https://developer.apple.com/design/human-interface-guidelines/motion
+- Material Design motion guidance for spatial continuity and state transitions: https://m3.material.io/styles/motion/overview
+- Nielsen Norman Group for visual hierarchy, scannability, and usability evidence: https://www.nngroup.com/articles/visual-hierarchy-ux-definition/
+
+Use the sources as constraints, not as a style to copy. Cite links in the report/summary when they shaped the redesign.
+
 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.
@@ -112,7 +140,9 @@ For App / Redesign / Section scope on multi-file work:
 
 Each agent receives:
 - `qualia-design/design-laws.md` + the matching register file
+- `qualia-design/frontend.md`, `design-reference.md`, and `graphics.md` for App / Redesign / Loop scopes
 - `PRODUCT.md` + `DESIGN.md` (inlined)
+- Online research anchors for Redesign scope, summarized in 3-6 bullets with links
 - Its 5 files (paths + contents)
 - Instruction: apply the Design Quality Rubric per file. Fix every dimension scoring < 3. Make literal edits. Do NOT change logic — only styling.
 
@@ -130,6 +160,21 @@ For Component scope: do the work in main context. Read, fix, verify.
 | Motion intent | DESIGN.md §7 — easing, stagger, signature motion |
 | Microcopy | rename "Get Started" / "Learn More" to action-named CTAs |
 | Container depth | flatten card-on-card; remove side-stripe borders |
+| Complex graphics | graphics.md — add meaningful product/data/process visuals, not decoration |
+
+### Stage 2b — Complex Visual Layer (App / Redesign / Loop)
+
+For whole-app, redesign, and loop scopes, decide whether the page needs a stronger visual system.
+
+1. Read `qualia-design/graphics.md`.
+2. Inspect the product/domain from PRODUCT.md and CONTEXT.md.
+3. Choose one:
+   - **No complex visual**: explain why typography/layout alone is stronger.
+   - **Bitmap/media**: real/generative/search asset that reveals product/place/person/state.
+   - **Diagram/data**: custom SVG/canvas/chart that explains relationships.
+   - **3D/canvas**: Three.js or canvas scene for spatial/product/system experience.
+4. If adding a visual, implement it as a first-viewport or primary-section signal, not a tiny decoration.
+5. Verify mobile framing, reduced-motion fallback, contrast, and nonblank rendering.
 
 ### Stage 3 — Runtime gates (App / Section / Redesign only — needs dev server)
 
@@ -170,7 +215,7 @@ For each iteration:
 
 1. Capture all 3 viewports
 2. Pass to a vision-model agent with `qualia-design/design-rubric.md` as the prompt anchor + DESIGN.md as the spec
-3. The agent scores 8 dimensions, anchored 1-5, with evidence per dimension
+3. The agent scores 9 dimensions, anchored 1-5, with evidence per dimension
 4. Apply fixes ONLY to dimensions scored 1 or 2 (don't nitpick 3s; prevents oscillation)
 5. STOP if: all dimensions ≥ 3 (success), OR any dimension regressed from previous iteration (regression-stop), OR 2 iterations reached (hard cap)
 
@@ -208,7 +253,7 @@ npx tsc --noEmit 2>&1 | tail -10
 
 ### Stage 7 — Commit & state
 
-For Critique scope: write the report to `.planning/polish-critique-{timestamp}.md` and STOP. Do not edit, do not commit.
+For Critique scope: create `.planning/reports/polish/`, write the report to `.planning/reports/polish/polish-critique-{timestamp}.md`, and STOP. Do not edit, do not commit.
 
 For all other scopes:
 
@@ -219,7 +264,7 @@ polish({scope}): {brief summary}
 
 - {key change 1}
 - {key change 2}
-- rubric scores: typography {N}, color {N}, ..., aggregate {N}/40
+- rubric scores: typography {N}, color {N}, graphics {N}, ..., aggregate {N}/45
 
 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 EOF
@@ -229,7 +274,7 @@ EOF
 If this is the FINAL polish before deploy (Handoff milestone, last phase):
 
 ```bash
-node ~/.claude/bin/state.js transition --to polished
+node ${QUALIA_BIN}/state.js transition --to polished
 ```
 
 Otherwise, no state transition (polish is now a normal verb, not a phase boundary).
@@ -237,21 +282,21 @@ Otherwise, no state transition (polish is now a normal verb, not a phase boundar
 ### Output
 
 ```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js ok "Scope: {component|section|app|redesign|critique|quick}"
-node ~/.claude/bin/qualia-ui.js ok "Files: {N}"
-node ~/.claude/bin/qualia-ui.js ok "Slop-detect: {N critical, M high, K medium}"
-node ~/.claude/bin/qualia-ui.js ok "Rubric aggregate: {N}/40 (avg {N})"
-node ~/.claude/bin/qualia-ui.js ok "Vision iterations: {0|1|2}"
-node ~/.claude/bin/qualia-ui.js ok "Drift findings: {N}"
-node ~/.claude/bin/qualia-ui.js end "POLISHED" "{next command — depends on context}"
+node ${QUALIA_BIN}/qualia-ui.js divider
+node ${QUALIA_BIN}/qualia-ui.js ok "Scope: {component|section|app|redesign|critique|quick}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Files: {N}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Slop-detect: {N critical, M high, K medium}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Rubric aggregate: {N}/45 (avg {N})"
+node ${QUALIA_BIN}/qualia-ui.js ok "Vision iterations: {0|1|2}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Drift findings: {N}"
+node ${QUALIA_BIN}/qualia-ui.js end "POLISHED" "{next command — depends on context}"
 ```
 
 ## Rules
 
 1. **Read before write.** Understand every file before changing it.
 2. **DESIGN.md is law.** If a project decision exists, follow it. Don't override.
-3. **Don't break functionality.** Only change styling, never logic.
+3. **Don't repair functionality here.** Only change styling, layout, copy polish, accessibility attributes, and design tokens already authorized by DESIGN.md. Route logic/data/config bugs to `/qualia-fix`.
 4. **Slop is a bug.** Critical-severity findings block commit. No overriding the script.
 5. **TypeScript must pass** after every change.
 6. **One commit per polish run** — not per category, not per file.