qualia-framework 5.1.0 → 5.4.0

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

@@ -63,14 +63,20 @@ function fingerprintIssue(issue) {
 function cmdInit() {
   const statePath = flag("--state");
   if (!statePath) { console.error("--state required"); exit(2); }
-  const url = flag("--url");
-  if (!url) { console.error("--url required"); exit(2); }
+  const routesFlag = flag("--routes");
+  const urlFlag = flag("--url");
+  if (!routesFlag && !urlFlag) { console.error("--url or --routes required"); exit(2); }
+  const urls = routesFlag
+    ? routesFlag.split(",").map((s) => s.trim()).filter(Boolean)
+    : [urlFlag];
   const max = flagInt("--max", 8);
   const budget = flagInt("--budget", 100000);
   const state = {
-    url,
+    url: urls[0],          // primary URL (backward compat with single-route SKILL.md)
+    urls,                  // full list — multi-route mode when length > 1
     brief_path: flag("--brief", null),
     reference_path: flag("--ref", null),
+    reduced_motion: argv.includes("--reduced-motion"),
     max_iterations: max,
     token_budget: budget,
     tokens_used: 0,
@@ -234,8 +240,13 @@ function cmdReport() {
   const lines = [];
   lines.push(`# Visual-Polish Loop Report`);
   lines.push("");
-  lines.push(`- **URL:** ${state.url}`);
+  if (Array.isArray(state.urls) && state.urls.length > 1) {
+    lines.push(`- **URLs (${state.urls.length}):** ${state.urls.join(", ")}`);
+  } else {
+    lines.push(`- **URL:** ${state.url}`);
+  }
   lines.push(`- **Brief:** ${state.brief_path || "_(none)_"}`);
+  if (state.reduced_motion) lines.push(`- **Reduced motion:** forced`);
   lines.push(`- **Started:** ${state.started_at}`);
   lines.push(`- **Final verdict:** ${state.verdict.toUpperCase()}${state.kill_reason ? ` — ${state.kill_reason}` : ""}`);
   lines.push(`- **Iterations:** ${state.iteration} / ${state.max_iterations}`);
@@ -286,12 +297,22 @@ switch (cmd) {
     console.log(`loop.mjs — orchestrator for /qualia-polish-loop
 
 Commands:
-  init       --state PATH --url URL [--brief PATH] [--ref PATH] [--max 8] [--budget 100000]
+  init       --state PATH (--url URL | --routes URL1,URL2,...) [--brief PATH] [--ref PATH] [--max 8] [--budget 100000] [--reduced-motion]
   record     --state PATH --eval PATH
   status     --state PATH
   commit-fix --state PATH --file PATH --slug TEXT
   report     --state PATH > report.md
 
+Multi-route mode (v5.2):
+  --routes wins over --url. State stores both state.url (first, backward
+  compat) and state.urls (full list). Orchestrator drives capture+eval
+  per URL; aggregate scores are min across URLs and viewports.
+
+Reduced-motion mode (v5.2):
+  --reduced-motion is recorded in state.reduced_motion. Capture script
+  is invoked with --reduced-motion which forces prefers-reduced-motion.
+  Vision evaluator scores motion on CSS-declaration quality only.
+
 Exit codes (record):
   0 = success (all dims >= 3)    1 = continue (more iterations needed)
   2 = invocation error            3 = killed (regression / budget / max)`);

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

@@ -26,7 +26,7 @@ import { homedir } from "node:os";
 
 // ── Arg parsing ──────────────────────────────────────────────────────────
 function parseArgs() {
-  const args = { url: null, out: null, viewports: [375, 768, 1440], wait: 1500 };
+  const args = { url: null, out: null, viewports: [375, 768, 1440], wait: 1500, reducedMotion: false };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--url" && argv[i + 1]) args.url = argv[++i];
@@ -34,11 +34,16 @@ function parseArgs() {
     else if (a === "--viewports" && argv[i + 1]) {
       args.viewports = argv[++i].split(",").map((s) => parseInt(s, 10)).filter((n) => Number.isFinite(n) && n > 0);
     } else if (a === "--wait" && argv[i + 1]) args.wait = parseInt(argv[++i], 10);
+    else if (a === "--reduced-motion") args.reducedMotion = true;
     else if (a === "--help" || a === "-h") {
       console.log(`playwright-capture.mjs — Screenshot capture for /qualia-polish-loop
 
 Usage:
-  node playwright-capture.mjs --url <url> --out <dir> [--viewports 375,768,1440] [--wait 1500]
+  node playwright-capture.mjs --url <url> --out <dir> [--viewports 375,768,1440] [--wait 1500] [--reduced-motion]
+
+Flags:
+  --reduced-motion   Force prefers-reduced-motion: reduce in the captured page.
+                     Use when the brief explicitly opts out of motion (a11y mode).
 
 Backend selection (auto):
   1. Playwright   — import('playwright') if installed
@@ -82,13 +87,15 @@ async function captureViaPlaywright(args) {
       const height = viewportHeight(width);
       const file = join(args.out, `${name}-${width}.png`);
       try {
-        const ctx = await browser.newContext({ viewport: { width, height }, deviceScaleFactor: 1 });
+        const ctxOpts = { viewport: { width, height }, deviceScaleFactor: 1 };
+        if (args.reducedMotion) ctxOpts.reducedMotion = "reduce";
+        const ctx = await browser.newContext(ctxOpts);
         const page = await ctx.newPage();
         await page.goto(args.url, { waitUntil: "networkidle", timeout: 30000 });
         if (args.wait > 0) await page.waitForTimeout(args.wait);
         await page.screenshot({ path: file, fullPage: false });
         await ctx.close();
-        results.push({ viewport: name, width, height, file, ok: true, backend: "playwright" });
+        results.push({ viewport: name, width, height, file, ok: true, backend: "playwright", reducedMotion: !!args.reducedMotion });
       } catch (err) {
         results.push({ viewport: name, width, height, file, ok: false, backend: "playwright", error: err.message });
       }
@@ -140,8 +147,9 @@ function captureViaChromeBinary(args, binary) {
       `--window-size=${width},${height}`,
       `--screenshot=${file}`,
       `--virtual-time-budget=${Math.max(args.wait + 1000, 3000)}`,
-      args.url,
     ];
+    if (args.reducedMotion) flags.push("--force-prefers-reduced-motion");
+    flags.push(args.url);
     const r = spawnSync(binary, flags, { encoding: "utf8", timeout: 30000 });
     let ok = r.status === 0 && existsSync(file);
     let size = 0;
@@ -152,6 +160,7 @@ function captureViaChromeBinary(args, binary) {
     results.push({
       viewport: name, width, height, file, ok,
       backend: "chrome-binary", binary,
+      reducedMotion: !!args.reducedMotion,
       ...(ok ? {} : { error: r.stderr ? r.stderr.split("\n").slice(0, 3).join(" / ") : `exit ${r.status}` }),
     });
   }

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

@@ -3,7 +3,7 @@
  * score.mjs -- Qualia visual-polish loop scoring utility.
  *
  * Takes a JSON object with 8 dimension scores and computes pass/fail
- * per the design rubric formula from rules/design-rubric.md.
+ * per the design rubric formula from qualia-design/design-rubric.md.
  *
  * Usage:
  *   echo '{"typography":3,"color":2,"spatial":3,"layout":3,"shadow":3,"motion":3,"microcopy":3,"container":3}' | node score.mjs

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 | `rules/frontend.md` + `skills/qualia-design/SKILL.md` |
+| Design regression — fonts off, contrast fail | `qualia-design/frontend.md` + `skills/qualia-design/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-prd/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: qualia-prd
+description: "Synthesize the current conversation into a durable Product Requirements Document (PRD) at .planning/PRD-{slug}.md. Optionally opens a parent GitHub issue. No interview — synthesizes what's already been discussed. Trigger on 'qualia-prd', 'turn this into a PRD', 'write this up as a feature spec', 'make a spec from this discussion', 'PRD this', 'externalize this idea', 'capture this as a spec'. Pairs with /qualia-issues to break the PRD into vertical-slice issues. Distinct from /qualia-plan (phase-operational) — /qualia-prd is feature-durable. v5.3 flagship from Matt Pocock's /to-prd pattern."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+argument-hint: "[slug] [--issue] [--no-issue] [--update PATH]"
+---
+
+# /qualia-prd — Conversation → durable feature spec
+
+You've been discussing a feature in chat. `/qualia-prd` synthesizes that conversation into a durable PRD on disk so the spec lives outside the chat context. From there, `/qualia-issues` can split it into vertical-slice GH issues, and `/qualia-plan` can plan a phase against it.
+
+**Distinct from `/qualia-new`:** `/qualia-new` is project setup (one-shot — JOURNEY.md, PRODUCT.md, CONTEXT.md). `/qualia-prd` is mid-project feature spec capture. You'll run it dozens of times across a project's life; you run `/qualia-new` once.
+
+## When to use
+
+- Mid-project, when a feature has been discussed enough that you want it durable
+- Before `/qualia-issues` so the issues link back to a real spec
+- Before `/qualia-plan` if the phase needs a feature spec upstream of it
+- When the conversation is about to compact and the PRD context would be lost
+
+## Pre-flight
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner plan
+```
+
+| Gate | Check | If fail |
+|---|---|---|
+| In a project | `.planning/` exists | HALT — "Run `/qualia-new` first or use `/qualia-quick` for one-off work" |
+| PRODUCT.md present | `.planning/PRODUCT.md` readable | NUDGE — proceed but recommend running `/qualia-new` to seed PRODUCT.md |
+| CONTEXT.md present | `.planning/CONTEXT.md` readable | NUDGE — PRD will use ad-hoc terminology instead of the glossary |
+| Working tree | `git status --porcelain` empty | OK to be dirty — PRD is additive, no logic changes |
+| Slug | First arg or auto-derive from first heading | Auto-derive: kebab-case the conversation's main feature topic |
+
+## Process
+
+### 1. Slug + path
+
+```bash
+SLUG="${1:-$(date +%Y%m%d)-feature}"   # or auto-derive from conversation
+PRD_PATH=".planning/PRD-${SLUG}.md"
+```
+
+If `--update PATH` is provided, update an existing PRD instead of writing a new one. The synthesis preserves existing sections that haven't been touched in conversation; only changed sections get rewritten.
+
+### 2. Spawn synthesizer (forked subagent — preserves taste, cheap on context)
+
+The synthesis runs in a **forked subagent**. Forks inherit the full conversation history + share the prompt cache, so the agent can pull the design discussion, decisions, ADR-worthy moments, and user voice without re-loading anything. The fork writes the PRD file and returns just the path + 1-line summary — keeps the parent session lean.
+
+```
+Agent(
+  subagent_type="general-purpose",
+  description="Synthesize conversation → PRD",
+  prompt=`
+You are synthesizing this conversation's feature discussion into a durable PRD.
+
+# Output location
+Write to: ${PRD_PATH}
+
+# Inputs you have (from forked context)
+- The full conversation up to this point
+- @.planning/PRODUCT.md  (project register, voice, anti-references)
+- @.planning/CONTEXT.md  (domain glossary — USE these terms, do not invent synonyms)
+- @.planning/decisions/*.md (ADRs constraining the design space)
+
+# PRD structure (copy this skeleton; fill from conversation)
+
+\`\`\`markdown
+---
+name: {feature name}
+slug: ${SLUG}
+created: ${date}
+status: draft | accepted | shipped | abandoned
+---
+
+# {Feature name}
+
+## Why this exists
+{1-3 sentences: what problem does this solve, for whom, why now}
+
+## User stories
+- As a {persona}, I want to {do X} so that {outcome}.
+- ...
+
+## Acceptance criteria
+Observable, testable behaviors. Each must be verifiable post-build.
+- [ ] {criterion 1}
+- [ ] {criterion 2}
+
+## Out of scope (mandatory)
+What this feature is NOT. Pin this down so scope creep is detectable.
+- {explicit non-goal 1}
+- {explicit non-goal 2}
+
+## Modules touched
+List the deep modules / files / packages this PRD will modify or create.
+Use CONTEXT.md domain language. Surface interface changes explicitly.
+
+| Module | Interface change | Rationale |
+|---|---|---|
+| {module} | {new method / removed export / signature change} | {why} |
+
+## Testing decisions
+Which behaviors get tests, what kind (unit / integration / e2e), where the
+seams are. /qualia-test --tdd will read this.
+
+## Open questions
+Things the conversation flagged but didn't resolve. /qualia-discuss can
+walk these down before /qualia-plan.
+
+## References
+- Conversation timestamp: {ISO}
+- Related ADRs: docs/adr/...
+- Related PRDs: .planning/PRD-...
+\`\`\`
+
+# Discipline
+- NO interview. Synthesize what was DISCUSSED. If a section has nothing in
+  the conversation, leave a TODO marker — do NOT invent.
+- Use CONTEXT.md domain terms. If the user said "lesson" but CONTEXT.md says
+  "module", normalize to "module" and note the alias.
+- Voice = PRODUCT.md voice. No "Welcome to" / "Get Started" / em-dashes in
+  user-facing copy snippets.
+- Output: write the file, then return ONLY \`{ "path": "...", "summary": "1 sentence" }\`.
+`
+)
+```
+
+### 3. Optional GH issue
+
+If `--issue` (or default when `gh` is configured AND `.planning/agents/tracker.md` exists), open a parent issue linking to the PRD path:
+
+```bash
+PRD_BODY=$(cat "${PRD_PATH}")
+gh issue create \
+  --title "PRD: {feature name}" \
+  --body-file "${PRD_PATH}" \
+  --label "prd,needs-triage"
+```
+
+Pass `--no-issue` to skip. The PRD itself is the source of truth — the GH issue is a notification surface.
+
+### 4. Commit
+
+```bash
+git add "${PRD_PATH}"
+git -c user.name="Qualia Solutions" -c user.email="info@qualiasolutions.net" \
+  commit -m "prd(${SLUG}): {feature name}"
+```
+
+### 5. End-card + next-command hint
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "PRD: ${PRD_PATH}"
+node ~/.claude/bin/qualia-ui.js ok "Issue: {url or 'skipped'}"
+node ~/.claude/bin/qualia-ui.js end "PRD CAPTURED" "/qualia-issues   # break into vertical slices"
+```
+
+## Token discipline (mandatory)
+
+This skill is the v5.3 reply to Matt's instruction-budget thesis. Three rules:
+
+1. **Forked subagent, file output.** The synthesis runs in a fork; main session never sees the full PRD body. Only `{path, summary}` flows back.
+2. **No re-summarization.** When the parent session needs the PRD later, it Reads the file (or a later skill does). Never paste the PRD body into chat to "confirm."
+3. **Fork prefix is stable.** Role + PRD skeleton are stable across spawns — Anthropic prompt caching applies. Per-invocation cost is ~5K tokens for the fork + ~2K for the synthesis output.
+
+## Failure modes
+
+| Symptom | Cause | Action |
+|---|---|---|
+| `.planning/ not found` | Not in a Qualia project | HALT; recommend `/qualia-new` or `/qualia-quick` |
+| Conversation has no clear feature topic | Skill invoked too early | NUDGE — ask the user "what feature are we PRD-ing? Pick a slug or paste a 1-line summary" |
+| `gh` not configured | No GitHub auth | Skip issue creation silently; print PRD path |
+| PRD path collision | Slug already exists | Append `-2`, `-3` to slug; surface to user |
+| Empty conversation context | Fresh session | HALT — "/qualia-prd needs a discussion to synthesize. Discuss first, then run." |
+
+## Rules
+
+1. **Don't interview.** This is synthesis, not a deep-dive. If gaps exist, mark TODO and recommend `/qualia-discuss`.
+2. **CONTEXT.md is law.** Use the project's terms. Don't invent.
+3. **One PRD per feature.** If two features got conflated in conversation, write two PRDs and link them.
+4. **Voice match.** PRODUCT.md voice. No generic SaaS copy.
+5. **Forked context, file output.** Token discipline above.
+6. **Commit immediately.** PRDs are durable artifacts — they ship in git.
+
+## Pairs with
+
+- `/qualia-discuss` — run BEFORE if the conversation has open questions
+- `/qualia-issues` — run AFTER to break PRD into vertical-slice GH issues
+- `/qualia-plan` — run AFTER `/qualia-issues` if you want a phase plan
+- `/qualia-new` — runs ONCE at project setup; `/qualia-prd` is the per-feature equivalent

package/skills/qualia-quick/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-quick
-description: "Fast path for small tasks — bug fixes, tweaks, hot fixes. Skips full phase planning. Trigger on 'quick fix', 'small change', 'tweak', 'hot fix', 'one-line fix', 'quick edit', 'small bug'."
+description: "Fast inline path for trivial fixes — ≤1 hour, typically 1 file, no plan, NO subagent spawn. The current Claude does the work directly. For a 1-5 file change that justifies a fresh builder context, use /qualia-task instead. Trigger on 'quick fix', 'small change', 'tweak', 'hot fix', 'one-line fix', 'typo', 'config tweak'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-research
-description: "Deep-research a niche domain or library BEFORE planning a specific phase. Spawns the researcher agent with Context7/WebFetch access. Writes to .planning/phase-{N}-research.md."
+description: "Deep-research a niche domain or library BEFORE planning a specific phase. Spawns the researcher agent with Context7/WebFetch access. Writes to .planning/phase-{N}-research.md. Triggers: 'research X library', 'research the domain before planning', 'study Stripe webhooks', 'how do others do RAG', 'best practices for X', 'compare libraries', 'I need depth before planning phase N'. Distinct from /qualia-recall (which queries the local Obsidian vault) and /qualia-discuss (which interviews the user)."
 allowed-tools:
   - Bash
   - Read
@@ -75,7 +75,8 @@ Reqs: {REQ-IDs for this phase}
 
 <output_path>.planning/phase-{N}-research.md</output_path>
 
-Priority: Context7 → WebFetch → WebSearch.
+Priority: NotebookLM (cross-notebook query) → local knowledge layer (knowledge.js search + qualia-recall) → Context7 → WebFetch → WebSearch.
+Skip web round when local sources cover the question with confidence ≥ MEDIUM (per agents/researcher.md §1b).
 Include: recommendation, rationale, versions, code examples, alternatives, pitfalls, sources.
 ", subagent_type="qualia-researcher", description="Phase {N} research")
 ```
@@ -123,4 +124,5 @@ node ~/.claude/bin/qualia-ui.js end "PHASE {N} RESEARCH DONE" "/qualia-plan {N}"
 1. **One session per run.** Don't research phases 1-5 in one call.
 2. **Must produce a file.** Research in conversation only is worthless.
 3. **Honor locked decisions.** Don't research alternatives to locked choices.
-4. **Context7 first.** Try Context7 MCP before WebFetch.
+4. **Local-first.** Drain NotebookLM and `~/qualia-memory` before any external call. The team has already researched most domains we touch — querying existing notebooks is near-zero token cost AND higher-quality than fresh WebSearch.
+5. **Context7 before WebFetch.** When you do go external, Context7 first for libraries; only WebFetch for non-library content (blog posts, case studies, post-mortems).

package/skills/qualia-road/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-road
-description: "Show the Qualia workflow map in the terminal — Project → Journey → Milestones → Phases → Tasks. Lists every command, when to use it, and how phases chain. Use when user asks 'how does Qualia work', 'what's the workflow', 'show me the road', 'what command does X', 'how do projects flow', or is new to the framework. (For an interactive HTML reference instead, use /qualia-help.)"
+description: "TERMINAL workflow map — Project → Journey → Milestones → Phases → Tasks. Use this in headless/SSH/no-browser sessions or when the user asks for the road in chat. For the HTML reference (default when a browser is available), use /qualia-help. Triggers: 'how does Qualia work', 'what's the workflow', 'show me the road', 'what command does X', 'how do projects flow', 'in terminal please', SSH context."
 disable-model-invocation: true
 allowed-tools:
   - Read
@@ -45,14 +45,24 @@ 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+)
+## /qualia-polish-loop -- autonomous visual QA (v5.1+, hardened in v5.2)
 ```
-/qualia-polish-loop http://localhost:3000     screenshot + eval + fix loop
-/qualia-polish-loop {url} --max 4            cap iterations
-/qualia-polish-loop {url} --ref design.png   anchor to reference image
+/qualia-polish-loop http://localhost:3000                screenshot + eval + fix loop
+/qualia-polish-loop {url} --max 4                       cap iterations
+/qualia-polish-loop {url} --ref design.png              anchor to reference image
+/qualia-polish-loop {url} --reduced-motion              force prefers-reduced-motion (v5.2+)
+/qualia-polish-loop --routes /a,/b,/c                   multi-route sweep (v5.2+)
 ```
 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 (Matt Pocock gaps closed)
+```
+/qualia-prd            synthesize current conversation → .planning/PRD-{slug}.md (durable feature spec)
+/qualia-hook-gen       convert a CLAUDE.md/rules instruction into a deterministic pre-tool-use hook
+/qualia-optimize --deepen   now spawns 3 parallel interface-design variants per candidate (Step 5b)
+```
+`/qualia-prd` pairs with `/qualia-issues` to form the PRD → vertical-slice → execute loop. `/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+)
 Before high-stakes phases, run alignment skills against `.planning/CONTEXT.md` (domain glossary) and `.planning/decisions/` (ADRs):
 

package/skills/qualia-task/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-task
-description: "Builds a single focused task in a fresh builder context with atomic commit and validation. More structured than /qualia-quick, lighter than /qualia-build (no phase plan needed). Use when the user says 'build this one thing', 'add a component', 'implement this feature', 'qualia-task', or for any 1-5 file change outside a full phase."
+description: "Single focused task with a FRESH builder subagent spawn — 1-3 hours, 1-5 files, atomic commit, validation contract. Heavier than /qualia-quick (which runs inline with no spawn) but lighter than /qualia-build (which needs a phase plan). Use when the user says 'build this one thing', 'add a component', 'implement this feature', 'qualia-task', or for any 1-5 file feature outside a full phase."
 allowed-tools:
   - Bash
   - Read

package/templates/PRODUCT.md

@@ -49,7 +49,7 @@ Sites the project should NOT look like. Anti-references pin down what the design
 - {URL or descriptor} — ...
 ```
 
-For Brand register, these are usually saturated aesthetic lanes (see `rules/design-brand.md`).
+For Brand register, these are usually saturated aesthetic lanes (see `qualia-design/design-brand.md`).
 For Product register, these are usually patterns we don't want to inherit (e.g., "Salesforce Lightning — too dense, too many panels").
 
 ## Positive references (optional, ≤3)

package/tests/bin.test.sh

@@ -1200,11 +1200,11 @@ else
   fail_case "qualia-road missing qualia-polish-loop reference"
 fi
 
-# 108. package.json version is 5.1.x (multi-target install + polish-loop in v5.x line)
-if grep -qE '"5\.1\.' "$FRAMEWORK_DIR/package.json"; then
-  pass "package.json version is 5.1.x"
+# 108. package.json version is 5.x (5.1+ accepted; v5.1 / v5.2 share the v5 line)
+if grep -qE '"5\.[1234]\.' "$FRAMEWORK_DIR/package.json"; then
+  pass "package.json version is 5.x"
 else
-  fail_case "package.json version not 5.1.x"
+  fail_case "package.json version not 5.x"
 fi
 
 # 109. loop.mjs installs (orchestrator)
@@ -1428,12 +1428,159 @@ else
   fail_case "qualia-ui CLI broke"
 fi
 
-# 128. package.json bumped to 5.1.x
+# 128. package.json bumped to 5.x (5.1+ accepted; 5.2 is the v5.2 release)
 PKG_V=$($NODE -e 'console.log(require("'"$FRAMEWORK_DIR"'/package.json").version)')
-if echo "$PKG_V" | grep -qE "^5\.1\."; then
-  pass "package.json version bumped to 5.1.x ($PKG_V)"
+if echo "$PKG_V" | grep -qE "^5\.[1234]\."; then
+  pass "package.json version bumped to 5.x ($PKG_V)"
 else
-  fail_case "package.json version not bumped to 5.1.x" "got=$PKG_V"
+  fail_case "package.json version not 5.x" "got=$PKG_V"
+fi
+
+echo ""
+echo "--- v5.2.0 (polish-loop reliability) ---"
+
+# 129. loop.mjs init accepts --routes and stores the URL list
+TMP_S=$(mktmp)/qpl-routes.json
+mkdir -p "$(dirname "$TMP_S")"
+EXIT=0; $NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" init \
+  --state "$TMP_S" \
+  --routes "http://x.test/a,http://x.test/b,http://x.test/c" \
+  --max 4 >/dev/null 2>&1 || EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && grep -q '"urls"' "$TMP_S" \
+   && grep -q '"http://x.test/a"' "$TMP_S" \
+   && grep -q '"http://x.test/b"' "$TMP_S" \
+   && grep -q '"http://x.test/c"' "$TMP_S"; then
+  pass "loop.mjs init --routes stores URL list (multi-route)"
+else
+  fail_case "loop.mjs --routes failed (exit=$EXIT)"
+fi
+
+# 130. state.url is the first --routes entry (backward compat with single-route SKILL.md)
+if grep -q '"url": "http://x.test/a"' "$TMP_S"; then
+  pass "loop.mjs init --routes sets state.url = first URL (backward compat)"
+else
+  fail_case "loop.mjs --routes did not set state.url to first entry"
+fi
+
+# 131. loop.mjs init accepts --reduced-motion and records it in state
+TMP_S2=$(mktmp)/qpl-rm.json
+mkdir -p "$(dirname "$TMP_S2")"
+EXIT=0; $NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" init \
+  --state "$TMP_S2" --url "http://x.test/" --reduced-motion >/dev/null 2>&1 || EXIT=$?
+if [ "$EXIT" -eq 0 ] && grep -q '"reduced_motion": true' "$TMP_S2"; then
+  pass "loop.mjs init --reduced-motion records state.reduced_motion=true"
+else
+  fail_case "loop.mjs --reduced-motion not recorded (exit=$EXIT)"
+fi
+
+# 132. playwright-capture.mjs accepts --reduced-motion (parses without error)
+EXIT=0; OUT=$($NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/playwright-capture.mjs" --help 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q -- "--reduced-motion"; then
+  pass "playwright-capture.mjs --help documents --reduced-motion"
+else
+  fail_case "playwright-capture --reduced-motion not in --help"
+fi
+
+# 133. loop.mjs init rejects when neither --url nor --routes given
+TMP_S3=$(mktmp)/qpl-nourl.json
+mkdir -p "$(dirname "$TMP_S3")"
+EXIT=0; $NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" init \
+  --state "$TMP_S3" --max 4 >/dev/null 2>&1 || EXIT=$?
+if [ "$EXIT" -eq 2 ]; then
+  pass "loop.mjs init rejects missing --url/--routes (exit 2)"
+else
+  fail_case "loop.mjs init did not reject missing URL (exit=$EXIT)"
+fi
+
+# 134. loop.mjs report mentions multi-route when state.urls > 1
+TMP_S4=$(mktmp)/qpl-rep.json
+mkdir -p "$(dirname "$TMP_S4")"
+$NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" init \
+  --state "$TMP_S4" --routes "http://a/,http://b/" >/dev/null 2>&1
+REP=$($NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" report --state "$TMP_S4" 2>&1)
+if echo "$REP" | grep -q "URLs (2)"; then
+  pass "loop.mjs report renders multi-route header"
+else
+  fail_case "loop.mjs report missing multi-route header"
+fi
+
+echo ""
+echo "--- v5.3.0 (Matt Pocock gaps: prd, hook-gen, parallel-interface) ---"
+
+# Re-install for v5.3 assertions (TMP from #99 may have v5.1 state)
+TMP=$(mktmp)
+echo "QS-FAWZI-01" | HOME="$TMP" $NODE "$INSTALL_JS" >/dev/null 2>&1
+
+# 135. qualia-prd skill installs
+if [ -f "$TMP/.claude/skills/qualia-prd/SKILL.md" ]; then
+  pass "qualia-prd skill installs"
+else
+  fail_case "qualia-prd SKILL.md missing after install"
+fi
+
+# 136. qualia-prd description mentions PRD synthesis from conversation
+if grep -q "synthesize\|Synthesize" "$TMP/.claude/skills/qualia-prd/SKILL.md" \
+   && grep -q "/qualia-issues" "$TMP/.claude/skills/qualia-prd/SKILL.md"; then
+  pass "qualia-prd describes synthesis flow + pairs with /qualia-issues"
+else
+  fail_case "qualia-prd missing synthesis or /qualia-issues link"
+fi
+
+# 137. qualia-prd documents fork-based token discipline
+if grep -qE "[Ff]orked subagent|fork.*subagent" "$TMP/.claude/skills/qualia-prd/SKILL.md" \
+   && grep -q "Token discipline" "$TMP/.claude/skills/qualia-prd/SKILL.md"; then
+  pass "qualia-prd documents fork-based synthesis (token discipline)"
+else
+  fail_case "qualia-prd missing fork/token-discipline section"
+fi
+
+# 138. qualia-hook-gen skill installs
+if [ -f "$TMP/.claude/skills/qualia-hook-gen/SKILL.md" ]; then
+  pass "qualia-hook-gen skill installs"
+else
+  fail_case "qualia-hook-gen SKILL.md missing after install"
+fi
+
+# 139. qualia-hook-gen documents the three enforcement patterns (block/rewrite/warn)
+if grep -q "Block" "$TMP/.claude/skills/qualia-hook-gen/SKILL.md" \
+   && grep -q "Rewrite" "$TMP/.claude/skills/qualia-hook-gen/SKILL.md" \
+   && grep -q "Warn" "$TMP/.claude/skills/qualia-hook-gen/SKILL.md"; then
+  pass "qualia-hook-gen documents block/rewrite/warn patterns"
+else
+  fail_case "qualia-hook-gen missing one of block/rewrite/warn patterns"
+fi
+
+# 140. qualia-hook-gen mandates Node hooks (cross-platform), not .sh scripts
+if grep -q "pure Node\|pure-node\|cross-platform" "$TMP/.claude/skills/qualia-hook-gen/SKILL.md" \
+   && grep -q "No \`.sh\`\|No \\.sh\|exit 0/2\|exit 2 to" "$TMP/.claude/skills/qualia-hook-gen/SKILL.md"; then
+  pass "qualia-hook-gen mandates pure-Node hooks (cross-platform discipline)"
+else
+  fail_case "qualia-hook-gen missing pure-Node mandate"
+fi
+
+# 141. qualia-optimize SKILL.md adds Step 5b (parallel-interface design)
+if grep -q "Step 5b\|Parallel Interface Design\|Wave 3" "$TMP/.claude/skills/qualia-optimize/SKILL.md" \
+   && grep -q "radically different" "$TMP/.claude/skills/qualia-optimize/SKILL.md"; then
+  pass "qualia-optimize Step 5b parallel-interface fan-out documented"
+else
+  fail_case "qualia-optimize missing Step 5b parallel-interface stage"
+fi
+
+# 142. qualia-optimize REFERENCE.md has the parallel-interface spawn template
+if grep -q "Parallel interface design prompt" "$TMP/.claude/skills/qualia-optimize/REFERENCE.md" \
+   && grep -q "Variant 1\|variant 1" "$TMP/.claude/skills/qualia-optimize/REFERENCE.md"; then
+  pass "qualia-optimize REFERENCE.md has parallel-interface spawn template"
+else
+  fail_case "qualia-optimize REFERENCE.md missing parallel-interface template"
+fi
+
+# 143. package.json version is 5.x (5.1+ accepted; v5.3 is the v5.3 release)
+PKG_V=$($NODE -e 'console.log(require("'"$FRAMEWORK_DIR"'/package.json").version)')
+if echo "$PKG_V" | grep -qE "^5\.[1234]\."; then
+  pass "package.json version is 5.x ($PKG_V) — v5.3 accepted"
+else
+  fail_case "package.json version not 5.x" "got=$PKG_V"
 fi
 
 echo ""