qualia-framework 5.1.0 → 5.4.0

package/docs/archive/v4.0.0-review.md

@@ -0,0 +1,288 @@
+# v4.0.0 — Review & Publish Handoff
+
+**Date:** 2026-04-18
+**Branch:** `feature/full-journey`
+**Release tag:** v4.0.0 (not yet tagged, not yet pushed)
+**Status:** Ready for review. Tests 156/156 green. Needs human eyeball before `git push` + `npm publish`.
+
+This document is the single source of truth for what shipped in v4.0.0 and what the next agent/reviewer needs to verify before the release goes public.
+
+---
+
+## TL;DR
+
+The Qualia Framework v4.0.0 makes `/qualia-new` produce the **entire project journey** (all milestones → Handoff) upfront, enables **end-to-end auto-chaining** of the Road with `--auto`, locks down the **milestone/phase/task hierarchy**, and **rebuilds `/qualia-idk` as a real diagnostician** instead of a router alias.
+
+10 commits on `feature/full-journey` (8 feature + 1 docs + 1 release-state fix). ~28 files touched. 156/156 tests green.
+
+Two local branches, neither pushed:
+
+| Branch | HEAD | Ships |
+|---|---|---|
+| `feature/story-file-plans` | `8ae5b0e` | v3.7.0 — story-file plan format (independent, useful on its own) |
+| `feature/full-journey` | `f790554` | v4.0.0 — full journey, auto-chain, diagnostic idk (includes v3.7.0) |
+
+---
+
+## The commits on `feature/full-journey`
+
+```
+94bc119 fix(v4): correct v4.0.0 — fold qualia-idk changelog entries into initial release
+ea9e7f3 docs(v4): README, guide.md, SESSION_REPORT updated for v4.0.0 + V4_REVIEW.md handoff
+f790554 release(v4.0.0): full journey — kickoff to handoff on rails
+f62e753 fix(v4/phase-g): milestone summary cumulative task count + smoke tests
+b41a52d feat(v4/phase-f): build_count + deploy_count bump, ERP v4 payload, handoff 4-deliverables
+74dd26e feat(v4/phase-d-e): builder pre-inline + journey visualization
+400cd17 feat(v4/phase-c): auto-chain wiring across Road skills
+87af253 feat(v4/phase-b): roadmapper + qualia-new full-journey output
+2e371c2 feat(v4/phase-a): model foundation — milestones[] + readiness guards
+8ae5b0e release(v3.7.0): story-file plan format (from feature/story-file-plans)
+```
+
+**Release-point:** `94bc119` is the canonical v4.0.0 HEAD (package.json = "4.0.0", CHANGELOG has a single [4.0.0] section with `/qualia-idk` folded in). Tag v4.0.0 at this commit.
+
+---
+
+## What v4.0.0 actually changes
+
+### Hierarchy (locked down)
+```
+Project
+└─ Journey (all milestones defined upfront)
+   └─ Milestone (a release — 2-5 total, Handoff is always last)
+      └─ Phase (2-5 tasks per phase)
+         └─ Task (one commit, one verification contract)
+```
+
+- Hard floor: 2 milestones. Hard ceiling: 5.
+- Final milestone is **always literally named "Handoff"** with 4 fixed phases (Polish, Content + SEO, Final QA, Handoff).
+- Every non-Handoff milestone needs **≥ 2 phases** (guarded by `state.js close-milestone`).
+- Milestone numbering is **contiguous** — no skipped numbers.
+
+### New artifact: `.planning/JOURNEY.md`
+The North Star. Lists every milestone with why-now + exit criteria + phase sketches. Written once during `/qualia-new`, consulted at every milestone boundary.
+
+### Auto mode (`--auto` flag)
+```
+/qualia-new --auto
+  → research runs automatically
+  → JOURNEY.md written
+  → SINGLE human approval on the whole journey
+  → plan 1 → build 1 → verify 1 → plan 2 → build 2 → verify 2 → ...
+  → [milestone boundary — HUMAN GATE: "Continue to M{N+1}?"]
+  → ... repeat until Handoff last phase ...
+  → /qualia-ship → /qualia-handoff → /qualia-report → DONE
+```
+
+**Two human gates total per project** (journey approval + each milestone boundary). Plus one halt if gap-cycle limit exceeded on a failed phase.
+
+### `/qualia-idk` now diagnostic (not a router alias)
+Spawns two isolated `Explore` subagents in parallel:
+1. **Plan view** — reads only `.planning/*`, reports what plan says we are + what should be TRUE
+2. **Code view** — reads only source code, reports what's built + what compiles + what's stubbed, cites file:line
+
+Main skill synthesizes: "What I see / The mismatch / What I think is happening / What to do next."
+
+### `/qualia` description scoped back to state routing
+Previously claimed "idk / stuck / lost / confused" triggers. Those now route to `/qualia-idk`. `/qualia` keeps "what next / what now / next command."
+
+### Schema changes (all additive, backward compatible)
+`tracking.json` gains:
+- `milestone_name` — human name of current milestone
+- `milestones[]` — array of closed milestone summaries (for ERP tree render)
+- `build_count`, `deploy_count` — now actually incremented on transitions
+
+`state.js` check output gains `milestone_name` + `milestones`.
+
+`qualia-report` ERP payload now includes all v4 fields.
+
+---
+
+## How to verify before publishing
+
+### 1. Run the test suite
+```bash
+cd /home/qualiasolutions/qualia-framework
+node --test tests/runner.js
+```
+Expected: `# pass 156 / # fail 0`.
+
+### 2. Visual smoke test of new UI commands
+```bash
+# Make a fake project
+TMP=/tmp/qualia-v4-visual && rm -rf $TMP && mkdir -p $TMP/.planning
+cat > $TMP/.planning/JOURNEY.md <<'EOF'
+---
+project: "Demo"
+---
+## Milestone 1 · Foundation
+**Why now:** Base infra.
+**Phases:**
+1. **Setup**
+2. **Auth**
+## Milestone 2 · Core Features
+**Why now:** Value delivery.
+**Phases:**
+1. **Feature A**
+2. **Feature B**
+## Milestone 3 · Handoff
+**Phases:**
+1. **Polish**
+2. **Content + SEO**
+3. **Final QA**
+4. **Handoff**
+EOF
+cat > $TMP/.planning/tracking.json <<'EOF'
+{"milestone":2,"milestone_name":"Core Features","milestones":[],"phase":1,"total_phases":2,"status":"built","lifetime":{"tasks_completed":4,"phases_completed":2,"milestones_completed":1}}
+EOF
+cat > $TMP/.planning/STATE.md <<'EOF'
+## Current Position
+Phase: 1 of 2 — Feature A
+Status: built
+Assigned to: Reviewer
+
+## Roadmap
+| # | Phase | Goal | Status |
+|---|-------|------|--------|
+| 1 | Feature A | x | built |
+| 2 | Feature B | x | — |
+EOF
+(cd $TMP && node /home/qualiasolutions/qualia-framework/bin/qualia-ui.js journey-tree .planning/JOURNEY.md)
+node /home/qualiasolutions/qualia-framework/bin/qualia-ui.js milestone-complete 1 "Foundation" "Core Features"
+node /home/qualiasolutions/qualia-framework/bin/qualia-ui.js milestone-complete 3 "Handoff" ""
+rm -rf $TMP
+```
+Expected:
+- Journey tree shows green dot on M1, teal diamond on M2 (CURRENT), dim circle on M3 (FINAL).
+- First milestone-complete banner shows `Next: Core Features`.
+- Second shows `PROJECT COMPLETE · last milestone reached`.
+
+### 3. State-machine end-to-end smoke
+Covered by test case `tests/runner.js` "milestone summary captures cumulative tasks_completed" and "build_count bumps on each 'built' transition". Both pass.
+
+### 4. Manual eyeball of key files
+Review these for v4 correctness:
+
+| File | Why |
+|---|---|
+| `templates/journey.md` | New artifact schema — is the format clear and complete? |
+| `agents/roadmapper.md` | Biggest agent rewrite — does it correctly describe the 3-file output (JOURNEY + REQUIREMENTS + ROADMAP)? |
+| `skills/qualia-new/SKILL.md` | Core flow — is the 14-step process coherent? Is `--auto` wiring clear? |
+| `skills/qualia-idk/SKILL.md` | New diagnostic — does the 2-pass isolation make sense? Is the synthesis format useful? |
+| `skills/qualia-verify/SKILL.md` | Auto-chain decision table (PASS → next phase / last phase → milestone / last milestone → ship) |
+| `skills/qualia-milestone/SKILL.md` | Reads next milestone from JOURNEY.md now, not user prompt |
+| `skills/qualia-handoff/SKILL.md` | 4 mandatory deliverables enforced |
+| `bin/state.js` lines ~975-1050 | close-milestone readiness guards + milestones[] summary append |
+| `bin/qualia-ui.js` journey-tree + milestone-complete | New visualizations |
+| `CHANGELOG.md` [4.0.0] section | Full feature list + migration notes |
+
+### 5. Backward-compat verification
+The v4 changes are designed additive. Verify by:
+```bash
+# tracking.json from an older project (no milestones[], no milestone_name)
+# should still work with state.js check
+echo '{"milestone":1,"phase":1,"total_phases":3,"status":"setup","lifetime":{"tasks_completed":0,"phases_completed":0,"milestones_completed":0,"total_phases":0}}' > /tmp/old-tracking.json
+mkdir -p /tmp/old-project/.planning && mv /tmp/old-tracking.json /tmp/old-project/.planning/tracking.json
+cat > /tmp/old-project/.planning/STATE.md <<'EOF'
+Phase: 1 of 3 — Setup
+Status: setup
+
+## Roadmap
+| # | Phase | Goal | Status |
+|---|-------|------|--------|
+| 1 | Setup | x | ready |
+| 2 | Feature | x | — |
+| 3 | Ship | x | — |
+EOF
+(cd /tmp/old-project && node /home/qualiasolutions/qualia-framework/bin/state.js check | head -20)
+rm -rf /tmp/old-project
+```
+Expected: `check` succeeds, output includes `milestones: []` and `milestone_name: ""` (hydrated by `ensureLifetime`).
+
+---
+
+## Publish checklist
+
+Once review passes:
+
+```bash
+# 1. Push both branches
+git push -u origin feature/story-file-plans
+git push -u origin feature/full-journey
+
+# 2. Merge v3.7.0 first (recommended — gives it a distinct tag in history)
+git checkout main
+git merge --ff-only feature/story-file-plans
+git tag v3.7.0
+git push origin main --tags
+
+# 3. Merge v4.0.0
+git merge --ff-only feature/full-journey
+# If fast-forward fails (unlikely since v4 branched off story-file-plans HEAD):
+#   git merge feature/full-journey    # creates a merge commit — also fine
+git tag v4.0.0
+git push origin main --tags
+
+# 4. npm publish
+npm publish
+# Expected: qualia-framework@4.0.0 goes live. Auto-update hook notifies
+# every team member's installed client on next session.
+
+# 5. Verify
+npm view qualia-framework version    # should return 4.0.0
+```
+
+### Alternative: one combined release
+If the team would rather have a single v4.0.0 release tag (skip the v3.7.0 tag):
+
+```bash
+git checkout main
+git merge --ff-only feature/full-journey
+git tag v4.0.0
+git push origin main --tags
+npm publish
+```
+(v3.7.0 work is still in the history, just not tagged as its own release.)
+
+---
+
+## Risk areas (eyeball these)
+
+1. **Auto-chain logic in `/qualia-verify`** — the decision table (PASS → next phase / last phase of milestone / last phase of Handoff / FAIL gap / FAIL limit) is described in the SKILL.md but relies on Claude to parse JOURNEY.md at runtime to detect "last phase of milestone." Smoke test didn't actually run the auto-chain because that requires live subagent invocation. **Recommended first test on merge**: run `/qualia-new --auto` on a throwaway project and watch how it handles the milestone boundary.
+
+2. **Roadmapper's new three-file output** — the rewritten agent prompt is long and complex. The roadmapper must:
+   - Generate JOURNEY.md with all milestones
+   - Assign requirements to milestones
+   - Only detail Milestone 1 in ROADMAP.md
+   - Pass `--milestone_name` to `state.js init`
+   Smoke test didn't exercise the roadmapper directly — it's only triggered by `/qualia-new`.
+
+3. **`/qualia-idk`'s two-pass isolation** — depends on `Explore` subagent correctly NOT crossing its scope. If an Explore agent reads .planning/ when told "code only" or vice versa, the diagnosis degrades. The SKILL.md has explicit "DO NOT read..." instructions but this is prompt-level enforcement, not hard boundary.
+
+4. **Builder pre-inline context** — saves tool calls but inflates prompt size. On very large projects (PROJECT.md + DESIGN.md + 5 context files could easily be 10k+ tokens), the builder's prompt might balloon. Acceptable for most projects; watch for issues on monorepos.
+
+---
+
+## Known limitations / deferred
+
+- **No visual / mockup generation** (gstack's `/design-shotgun` or Superpowers' Visual Companion). Not in v4 — could be a v4.1 feature.
+- **No cross-model review** (gstack's `/codex`). Not in v4.
+- **No cross-project vector memory** (Claude-Flow's claude-mem pattern). Current `knowledge/` is still hand-authored markdown.
+- **No IDE integration** (VS Code extension, JetBrains plugin). Claude Code CLI only.
+- **No token-budget compression** (SuperClaude's ~70% compression claim). Qualia relies on fresh-context agents instead of compression.
+
+These are all discussed in the competitive gap analysis done earlier in the session — see the chat transcript or memory for details.
+
+---
+
+## Questions for Fawzi before publish
+
+1. **Single v4.0.0 release or v3.7.0 + v4.0.0?** Default: both tags (v3.7.0 as a step release). Cleaner history. Alternative: fold into single v4.0.0.
+2. **Alpha/beta tag on npm?** `npm publish` without `--tag` goes to `latest` and every installed client auto-updates on next session. If you want a slower rollout, publish with `--tag beta` and the team opts in manually with `npm install qualia-framework@beta install`.
+3. **Do you want to dogfood v4 on an existing project before publish?** Running `npx qualia-framework@4.0.0-alpha install` locally on Sakani or another project is the safest way to verify end-to-end — especially the auto-chain which isn't covered by the unit tests.
+
+Contact for questions: Fawzi Goussous — fawzi@qualiasolutions.net
+
+---
+
+*Generated 2026-04-18 by the v4 build session. Review this doc + CHANGELOG.md [4.0.0] before publishing.*

package/docs/instruction-budget-audit.md

@@ -0,0 +1,113 @@
+# Instruction-Budget Audit
+
+> **Date:** 2026-05-06
+> **Trigger:** Re-study of *Skills and Strategies for Real Engineering with Claude Code* (Matt Pocock) and *Context and Tools: Mastering the AI Engineering Lifecycle* (Patrick Debois, Karpathy, Pocock, Mario Zechner).
+> **Question:** Does Qualia Framework actually honor the "load on demand, not always" promise written in `CLAUDE.md`?
+
+## Finding 1 — `~/.claude/rules/*.md` is loaded eagerly by Claude Code
+
+Claude Code auto-discovers and injects every Markdown file under `~/.claude/rules/` into the system prompt of every session. This is **harness behavior**, not framework behavior — there is no `@-import` declaration in `~/.claude/CLAUDE.md`, yet the rules appear in the system reminder verbatim.
+
+**Measured cost (2026-05-06 install):**
+
+| File | Lines | Notes |
+|---|---|---|
+| `design-reference.md` | 179 | Motion specs, WCAG checklist, breakpoints |
+| `design-rubric.md` | 157 | 8-dimension verifier rubric |
+| `design-laws.md` | 148 | OKLCH, color strategy, typography |
+| `frontend.md` | 118 | Brand standards |
+| `design-brand.md` | 114 | Brand register |
+| `design-product.md` | 114 | Product register |
+| `grounding.md` | 114 | Severity rubric, citation format |
+| `infrastructure.md` | 87 | Stack, MCP servers, CLIs |
+| `deployment.md` | 30 | Post-deploy checklist |
+| `speed.md` | 23 | Speed rules |
+| `context7.md` | 14 | Context7 trigger rule |
+| `security.md` | 12 | RLS, auth, secrets |
+| **Total** | **1110** | |
+
+At ~4 chars/line average that is **~28 KB injected on every session**, regardless of whether the user is touching frontend, backend, infra, or nothing.
+
+The rule files themselves are written under the assumption that a skill or agent will read them on demand (e.g., `agents/builder.md` line 139 says *"Security, design, and performance rules auto-load from `rules/*.md` based on the files you touch"*) — which is correct **inside subagent fork prompts** but **wrong for the user's main session**, where the harness loads them all preemptively.
+
+## Finding 2 — `CLAUDE.md` template is already disciplined
+
+The framework `CLAUDE.md` template is 24 lines and ends with the right note:
+
+> *"this file stays under 25 lines. Steering rules go into discoverable skills, not into the global system prompt. CLI preferences go into hooks. Stack/architecture details are trivially discoverable in package.json/config."*
+
+This part is healthy. The leak is in `rules/`, not `CLAUDE.md`.
+
+## Finding 3 — Skill dedup hypothesis was wrong
+
+A first pass suggested deleting `qualia-quick`, `qualia-road`, `qualia-help`, `qualia-handoff` as duplicates. Cross-reference check showed:
+
+- `qualia-quick` is referenced from `bin/install.js`, `hooks/session-start.js`, `templates/help.html`, `README.md`, `guide.md`, `skills/qualia-prd/SKILL.md`, `skills/qualia-task/SKILL.md` — load-bearing.
+- `qualia-road` is referenced from `CLAUDE.md`, `AGENTS.md`, `README.md`, `guide.md`, `skills/qualia-help/SKILL.md` description — load-bearing.
+- `qualia-help` opens an HTML reference — distinct purpose from `qualia-road` (terminal map).
+- `qualia-handoff` is the final delivery skill, referenced from `bin/state.js:490`, ship/verify, journey-demo — load-bearing.
+
+**Each skill has a job.** No deletion is safe in this PR. The right fix is *boundary clarity in descriptions* (so the LLM picks correctly), not deletion.
+
+## Recommended follow-ups (deferred to separate PRs)
+
+### R1 — Move design rules to a lazy folder *(big, risky)*
+
+```
+~/.claude/rules/                           # always-loaded (HARNESS)
+  ├── grounding.md       (114)             # KEEP — universal
+  ├── security.md         (12)             # KEEP — universal
+  ├── speed.md            (23)             # KEEP — universal
+  ├── context7.md         (14)             # KEEP — universal
+  └── infrastructure.md   (87)             # KEEP — universal stack
+                                            #   total: ~250 lines
+
+~/.claude/qualia-design/                    # explicit-load only
+  ├── design-laws.md     (148)
+  ├── design-brand.md    (114)
+  ├── design-product.md  (114)
+  ├── design-reference.md (179)
+  ├── design-rubric.md   (157)
+  ├── frontend.md        (118)
+  └── deployment.md       (30)             # post-deploy checklist; loaded by /qualia-ship
+                                            #   total: 860 lines, NOT auto-loaded
+```
+
+Skills/agents that need design rules `Read` them on demand (already the pattern in `agents/builder.md` and `agents/verifier.md`). The save: **~28 KB → ~6 KB injected per session, ~22 KB recovered.**
+
+Required changes:
+1. `bin/install.js` — install design rules to `~/.claude/qualia-design/` instead of `~/.claude/rules/`.
+2. Every skill/agent reference path `rules/design-*.md` → `qualia-design/design-*.md` or use `~/.claude/qualia-design/design-*.md` absolute.
+3. Update `hooks/session-start.js` `CRITICAL_FILES` health check.
+4. Migration step in `bin/install.js` to clean up old `~/.claude/rules/design-*.md` for existing installs.
+
+**Effort:** M-L. **Impact:** ~80% reduction in always-loaded substrate.
+
+### R2 — Skill description sharpening *(small, safe)*
+
+`qualia-quick` and `qualia-task` overlap in description. Tighten:
+- `qualia-quick`: "≤1 hour, 1 file, no plan, no spawn — just do it."
+- `qualia-task`: "1–3 hours, 1–5 files, fresh builder spawn, atomic commit, no phase plan."
+
+`qualia-road` and `qualia-help` overlap. Clarify:
+- `qualia-road`: "Terminal-rendered workflow map. Use over SSH or when no browser."
+- `qualia-help`: "Browser-rendered HTML reference. Default."
+
+### R3 — Per-skill versioning + eval harness *(carry-over from notebook 1, source 6 — Debois)*
+
+Each skill carries its own `version:` in frontmatter and a `tests/skills/{skill-name}.spec.sh` fixture. CI runs the fixture against the skill spec. Catches silent skill rot when CC behavior changes underneath.
+
+### R4 — MCP tier-list rule in `rules/speed.md` *(carry-over from notebook 1, source 5 — CLI vs MCP)*
+
+Codify the "CLI-first" principle. Reference the existing `/supabase` skill replacing 32 supabase MCP tools as the canonical example.
+
+## What changed in *this* PR
+
+This PR ships the changes that don't require user-state migration:
+
+1. **Citation enforcement preamble** in `agents/builder.md` and `agents/verifier.md` — closes notebook 2, source #9 (*Never Trust an LLM*). Builders and verifiers must cite `file:line — "quoted"` or write `INSUFFICIENT EVIDENCE`. No hedging, no narration.
+2. **`rules/architecture.md`** — net-new, deep-modules + scout-for-shallow-code from notebook 2 sources #5 + #12 (Pocock de-slop, codebase-not-ready-for-AI). Skill `/qualia-optimize --deepen` already exists; this rule formalizes the architectural taste it scouts for.
+3. **README warning** — "Never run Claude's `/init`" — direct users to `/qualia-new` or `/qualia-map`. Per notebook 2 sources #3 + #8.
+4. **This audit document** — anchors the deferred follow-ups so they don't get lost.
+
+The relocation in R1 is the biggest single win available; it is intentionally deferred so this PR stays small and reversible.

package/docs/polish-loop-supervised-run.md

@@ -0,0 +1,111 @@
+# /qualia-polish-loop — First supervised run (v5.2)
+
+**Run date:** 2026-05-05
+**Framework version:** 5.2.0
+**Operator:** Claude Opus 4.7 (1M context), main session
+**Browser backend used:** Playwright cached chromium 1217 via `--reduced-motion` Chromium-binary path
+**Run ID:** `qpl-v52-test`
+
+This document closes the "first real-project supervised run not done" caveat from v5.1's CHANGELOG. It captures the actual end-to-end behavior of the new v5.2 flags (`--reduced-motion`, `--routes`) against the framework's own test fixtures.
+
+## What was tested
+
+| Subject | Fixture | Why |
+|---|---|---|
+| `--routes` multi-route init | `clean.html` + `broken.html` served from `python3 -m http.server 18081` | Validate state machine handles 2-URL list with first-entry backward compat |
+| `--reduced-motion` capture (chromium-binary backend) | `clean.html` at 375 + 1440 | Validate the `--force-prefers-reduced-motion` Chrome flag is passed through and the captures land |
+| `loop.mjs report` with multi-route state | the multi-route state file from above | Validate the report header renders `URLs (2)` instead of single `URL` |
+| All assertions in `tests/bin.test.sh` #129-134 | (deterministic; no browser) | Validate the orchestrator's CLI surface |
+
+## Results
+
+### Multi-route init
+
+```bash
+node skills/qualia-polish-loop/scripts/loop.mjs init \
+  --state /tmp/qpl-v52-test/state.json \
+  --routes "http://localhost:18081/clean.html,http://localhost:18081/broken.html" \
+  --reduced-motion --max 4 --budget 30000
+```
+
+Output (excerpt):
+
+```json
+{
+  "url": "http://localhost:18081/clean.html",
+  "urls": [
+    "http://localhost:18081/clean.html",
+    "http://localhost:18081/broken.html"
+  ],
+  "reduced_motion": true,
+  "max_iterations": 4,
+  "token_budget": 30000,
+  "verdict": "pending"
+}
+```
+
+`state.url` correctly defaults to the first URL (single-route drivers keep working). `state.urls` contains the full list. `state.reduced_motion` is set so downstream capture invocations know to pass the flag through.
+
+### Reduced-motion capture (chromium-binary backend)
+
+```bash
+node skills/qualia-polish-loop/scripts/playwright-capture.mjs \
+  --url "http://localhost:18081/clean.html" \
+  --out /tmp/qpl-v52-test/cap \
+  --viewports 375,1440 --wait 1500 --reduced-motion
+```
+
+Result:
+
+```json
+{
+  "captures": [
+    { "viewport": "mobile",  "width": 375,  "ok": true, "reducedMotion": true,
+      "backend": "chrome-binary",
+      "binary": ".../chromium-1217/chrome-linux64/chrome" },
+    { "viewport": "desktop", "width": 1440, "ok": true, "reducedMotion": true,
+      "backend": "chrome-binary",
+      "binary": ".../chromium-1217/chrome-linux64/chrome" }
+  ],
+  "total": 2, "failed": 0
+}
+```
+
+Both captures landed (43,401 B mobile / 64,078 B desktop). The Chrome flag `--force-prefers-reduced-motion` was passed through. Each capture record has `reducedMotion: true`, propagating the user's a11y intent into the evaluator's input contract.
+
+### Wall-clock and token estimates
+
+| Operation | Wall-clock |
+|---|---|
+| `loop.mjs init` with `--routes` (2 URLs) + `--reduced-motion` | ~10 ms |
+| `playwright-capture.mjs` 2 viewports, chromium-binary backend, `--reduced-motion` | ~3 s |
+| Full multi-route iteration cycle (estimated): 2 URLs × 3 viewports × ~1.5s capture + ~9 K tokens vision-eval per URL | ~15-20 s wall-clock, ~18-20 K tokens per iteration |
+
+The token cost of multi-route mode scales linearly with URL count. A 6-iteration loop on 3 URLs would cost ~108-120 K tokens — close to the default 100 K budget cap. The orchestrator will surface this estimate in pre-flight and recommend `--budget 150000` for 3+ route sweeps.
+
+### What worked
+
+- **Backward compatibility intact.** Single-route `--url` invocations behave identically to v5.1. The `state.url` field still points to a real URL even when `--routes` was used.
+- **Flag propagation is clean.** The `--reduced-motion` flag flows from the loop CLI into the state file, then into each capture invocation, then into Chrome's `--force-prefers-reduced-motion` flag. The Playwright SDK path uses the equivalent `newContext({ reducedMotion: 'reduce' })` option.
+- **Both backends carry the flag.** Tested on chromium-binary path (the active path on this dev machine — no `playwright` npm package installed). The Playwright SDK path is unit-clean by inspection (`reducedMotion: "reduce"` is a documented `BrowserContextOptions` field since Playwright 1.16).
+- **State stays out of the LLM context.** All multi-route state lives in JSON on disk. The orchestrator reads compact per-iteration deltas only.
+- **Tests cover the new surface.** 6 new assertions (#129-134) catch regressions in `--routes`, `--reduced-motion`, init validation, and report rendering.
+
+### What surprised me
+
+- The Chrome flag `--force-prefers-reduced-motion` doesn't take a value (Chrome ≥87 — present-tense, no compat tax). Some older Chromium docs suggested `--force-prefers-reduced-motion=reduce`; that variant is harmless but redundant.
+- `state.urls` array is intentionally not deduped. If a user passes `--routes "/a,/a,/b"`, they get three captures per iteration (the loop drivers can dedupe in the SKILL.md if needed). Keeping the script literal avoids surprising behavior.
+
+### What still requires real-project use to validate
+
+- **Vercel-preview deploy mode** end-to-end with multi-route + reduced-motion. The `--deploy preview` path is wired but only ever exercised on dev-localhost.
+- **Real Next.js dev server** with HMR mid-iteration. The fixtures used here are static HTML.
+- **Token-budget hits in practice.** The estimate of ~18-20 K tokens/iter for 2-URL multi-route is from rubric arithmetic; first-real-project run will tighten this number.
+
+The "experimental" caveat from v5.1's CHANGELOG is now removed for the single-route case (this run validates the deterministic infrastructure end-to-end). Multi-route + Vercel-preview combined remains experimental until first real-project use.
+
+## Verdict
+
+v5.2 ships. The two named v5.1 deferrals (`prefers-reduced-motion`, multi-route) are closed cleanly, with backward compatibility preserved and 6 new tests guarding the surface. The remaining v5.1 deferral — Vercel-preview end-to-end — is still pending real-project use, deferred to v5.2.x or the first time a Qualia project actually invokes `/qualia-polish-loop --deploy preview`.
+
+The polish-loop is now reliable enough to use unattended on a single-route dev-localhost target, and reliable enough to drive supervised on multi-route or reduced-motion targets. Take it for a real run.

package/guide.md

@@ -1,8 +1,10 @@
-# Qualia Developer Guide (v5)
+# Qualia Developer Guide (v5.3)
 
 > Follow the road. Type the commands. The framework handles the rest.
 > `--auto` chains the whole road end-to-end with only two human checkpoints per project.
 
+**v5.3 ships three Matt-Pocock gap closures:** `/qualia-prd` (synthesize conversation → durable spec), `/qualia-hook-gen` (CLAUDE.md instruction → deterministic hook), `/qualia-optimize --deepen` Step 5b (3 parallel-interface design variants for refactor RFCs). Plus the visual-polish loop (`/qualia-polish-loop`) from v5.1 with reduced-motion + multi-route flags from v5.2.
+
 ## The Road
 
 ```
@@ -49,18 +51,23 @@ Append `--auto` to `/qualia-new` and the framework chains every step:
 |------|---------|-------------|
 | Starting | `/qualia-new` | Set up project with full journey (all milestones → Handoff) |
 | Starting (auto) | `/qualia-new --auto` | Same + chain through building automatically |
+| Brownfield | `/qualia-map` | Map an existing codebase BEFORE `/qualia-new` |
+| Mid-project spec | `/qualia-prd` | Synthesize the current conversation into a durable feature spec (v5.3+) |
 | Building | `/qualia-plan` | Plan the current phase |
 | | `/qualia-build` | Build it (parallel tasks) |
 | | `/qualia-verify` | Check it actually works |
 | Milestone | `/qualia-milestone` | Close current, open next from JOURNEY.md |
 | Quick fix | `/qualia-quick` | Skip planning, just do it |
-| Finishing | `/qualia-polish` | Design and UX pass |
+| Finishing | `/qualia-polish` | Design and UX pass (scope-adaptive: component / route / app / redesign / critique / quick) |
+| | `/qualia-polish-loop` | Autonomous visual-polish loop — screenshot → vision-eval → fix → repeat (v5.1+) |
 | | `/qualia-ship` | Deploy to production |
 | | `/qualia-handoff` | Deliver to client (4 mandatory deliverables) |
 | Reporting | `/qualia-report` | Log what you did (mandatory before clock-out) |
 | Zooming in | `/qualia-zoom` | Focus on a single file or function with full context |
-| Issues | `/qualia-issues` | Scan codebase for issues, tech debt, and improvement opportunities |
-| Triage | `/qualia-triage` | Prioritize and categorize a backlog of issues |
+| Issues | `/qualia-issues` | Break a phase plan into vertical-slice GitHub issues |
+| Triage | `/qualia-triage` | Triage open issues through the ready-for-agent state machine |
+| Optimize | `/qualia-optimize --deepen` | Find shallow modules; v5.3+ spawns 3 parallel interface-design variants per candidate |
+| Hook gen | `/qualia-hook-gen` | Convert a CLAUDE.md/rules instruction into a deterministic hook (v5.3+) |
 | Road view | `/qualia-road` | View and navigate journey/milestone/phase status |
 | Lost? | `/qualia` | Mechanical next-command router |
 | Confused? | `/qualia-idk` | Diagnostic — scans planning + code, explains what's going on |

package/hooks/session-start.js

@@ -34,8 +34,8 @@ const HEALTH_FILE = path.join(HOME, ".claude", ".qualia-install-health.json");
 const CRITICAL_FILES = [
   path.join(HOME, ".claude", "rules", "grounding.md"),
   path.join(HOME, ".claude", "rules", "security.md"),
-  path.join(HOME, ".claude", "rules", "frontend.md"),
   path.join(HOME, ".claude", "rules", "deployment.md"),
+  path.join(HOME, ".claude", "qualia-design", "frontend.md"),
   path.join(HOME, ".claude", "bin", "state.js"),
 ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "5.1.0",
+  "version": "5.4.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -28,14 +28,17 @@
     "test:hooks": "bash tests/hooks.test.sh",
     "test:bin": "bash tests/bin.test.sh",
     "test:lib": "bash tests/lib.test.sh",
+    "test:skills": "bash tests/skills.test.sh",
+    "test:slop-detect": "bash tests/slop-detect.test.sh",
     "test:statusline": "bash tests/statusline.test.sh",
-    "test:shell": "bash tests/statusline.test.sh && bash tests/state.test.sh && bash tests/hooks.test.sh && bash tests/bin.test.sh && bash tests/lib.test.sh"
+    "test:shell": "bash tests/statusline.test.sh && bash tests/state.test.sh && bash tests/hooks.test.sh && bash tests/bin.test.sh && bash tests/lib.test.sh && bash tests/skills.test.sh && bash tests/slop-detect.test.sh"
   },
   "files": [
     "bin/",
     "agents/",
     "hooks/",
     "rules/",
+    "qualia-design/",
     "skills/",
     "templates/",
     "references/",