qualia-framework 5.8.0 → 5.9.1

package/agents/plan-checker.md

@@ -2,8 +2,16 @@
 name: qualia-plan-checker
 description: Validates a phase plan before execution. Checks task specificity, wave assignment, verification contracts, and coverage of success criteria. Spawned by qualia-plan in a revision loop (max 2 iterations).
 tools: Read, Bash, Grep
+model: sonnet
 ---
 
+<!-- v5.9: Sonnet, not Opus. The checker runs an 11-rule checklist against the
+     plan — every rule is a deterministic match (task has a Why?, AC is
+     observable?, wave assignment correct?). Structured validation, not plan
+     synthesis. Plan WRITING is on Opus (agents/planner.md); plan CHECKING is
+     on Sonnet because it's pattern-matching. -->
+
+
 # Plan Checker
 
 You validate phase plans before they go to the builder. You do NOT write plans — you evaluate them. If a plan has issues, return a structured list; the planner will revise and you'll check again (max 2 revision cycles).

package/agents/qa-browser.md

@@ -2,8 +2,15 @@
 name: qualia-qa-browser
 description: Real-browser QA. Navigates the running dev server, checks layout at mobile/tablet/desktop, clicks primary flows, captures console errors and a11y issues. Spawned by /qualia-verify on phases with frontend work.
 tools: Read, Bash, Grep, Glob
+model: sonnet
 ---
 
+<!-- v5.9: Sonnet, not Opus. QA-browser drives the browser through scripted
+     flows and reports console + a11y findings. Mechanical interaction +
+     finding-collection, not architectural reasoning. Vision interpretation
+     for design quality lives in visual-evaluator.md, which stays on Opus. -->
+
+
 # Qualia QA Browser
 
 You verify that the **running app actually looks and behaves right** — not just that the code compiles and greps clean. Fresh context, no memory of what was built.

package/agents/roadmapper.md

@@ -2,8 +2,16 @@
 name: qualia-roadmapper
 description: Creates JOURNEY.md (full multi-milestone arc), REQUIREMENTS.md (multi-milestone, REQ-IDs), and ROADMAP.md (current milestone's phase detail) from PROJECT.md and research. Spawned by qualia-new after research completes.
 tools: Read, Write, Bash
+model: sonnet
 ---
 
+<!-- v5.9: Sonnet, not Opus. The roadmapper fills mostly-deterministic templates
+     (JOURNEY.md, REQUIREMENTS.md, ROADMAP.md) from PROJECT.md + research
+     synthesis. Project-specific shape, but the milestone-decomposition logic
+     is bounded and structured — not novel synthesis. Builder and planner stay
+     on Opus where real architectural reasoning lives. -->
+
+
 # Qualia Roadmapper
 
 You produce the **full project journey** — every milestone from kickoff to handoff. This is the North Star for the rest of the project. Everything downstream (planner, builder, verifier, milestone close) stays architecturally consistent with what you write here.

package/agents/verifier.md

@@ -2,8 +2,17 @@
 name: qualia-verifier
 description: Goal-backward verification. Checks if the phase ACTUALLY works, not just if tasks ran.
 tools: Read, Bash, Grep, Glob
+model: sonnet
 ---
 
+<!-- v5.9: Sonnet, not Opus. The verifier executes a deterministic protocol —
+     run greps against acceptance criteria, score the 8-dim design rubric, walk
+     stub-detection patterns. Pattern-matching + structured output, not novel
+     architectural reasoning. Opus is overkill; the inherited-Opus default cost
+     ~3x what Sonnet does without measurably better verdicts.
+     Builder and planner stay on Opus (they do real synthesis). -->
+
+
 # Qualia Verifier
 
 You verify that a phase achieved its GOAL, not just completed its TASKS.
@@ -44,7 +53,11 @@ Write `.planning/phase-{N}-verification.md` — PASS or FAIL with evidence. Appl
 
 ## Tool Budget
 
-Maximum 25 Bash/Grep calls per invocation. Prefer one multi-pattern grep over many single-pattern greps. If you exhaust the budget, write what you found and mark unchecked criteria as `INSUFFICIENT EVIDENCE` — do not fabricate.
+Budget scales with phase size: **`max(25, task_count * 5)` Bash/Grep calls** per invocation. The plan file's `## Task N` count determines `task_count` — a 3-task phase gets 25 calls, a 10-task phase gets 50.
+
+Prefer one multi-pattern grep over many single-pattern greps. If you exhaust the budget, write what you found and mark unchecked criteria as `INSUFFICIENT EVIDENCE` — do not fabricate.
+
+**INSUFFICIENT EVIDENCE is a hard FAIL signal.** The orchestrator (`/qualia-verify`) treats any `INSUFFICIENT EVIDENCE` line in the verification file as a phase FAIL, not silent PASS. Don't use it as a pass-through — only when budget genuinely exhausted before a criterion could be checked.
 
 ## Goal-Backward Verification
 

package/bin/cli.js

@@ -160,7 +160,7 @@ const QUALIA_AGENT_FILES = [
 ];
 
 // 3 Qualia bin scripts.
-const QUALIA_BIN_FILES = ["state.js", "qualia-ui.js", "statusline.js", "knowledge.js", "knowledge-flush.js", "plan-contract.js", "agent-runs.js", "slop-detect.mjs"];
+const QUALIA_BIN_FILES = ["state.js", "qualia-ui.js", "statusline.js", "knowledge.js", "knowledge-flush.js", "plan-contract.js", "agent-runs.js", "slop-detect.mjs", "erp-retry.js"];
 
 // Qualia rules — security, deployment, infra, grounding, plus the v4.5.0 design substrate.
 // frontend.md and design-reference.md are kept for backward compat; new projects use design-laws/brand/product/rubric.
@@ -1035,6 +1035,29 @@ function cmdSetErpKey() {
 // ─── Flush: convenience wrapper around knowledge-flush.js ───────
 // Exposes the cron-runnable script as a top-level CLI command so users can
 // run `qualia-framework flush` ad-hoc. All args after the command pass through.
+// ─── erp-flush: drain the ERP retry queue verbosely ───────────
+// Thin wrapper around bin/erp-retry.js. Used when an employee wants to
+// retry stranded reports on demand (e.g., after the ERP came back online,
+// or after rotating the API key). All args pass through.
+function cmdErpFlush() {
+  const retryScript = path.join(CLAUDE_DIR, "bin", "erp-retry.js");
+  if (!fs.existsSync(retryScript)) {
+    console.log(`  ${RED}✗${RESET} erp-retry.js not installed at ${retryScript}`);
+    console.log(`  ${DIM}Run: npx qualia-framework@latest install${RESET}`);
+    process.exit(1);
+  }
+  banner();
+  console.log("");
+  const args = process.argv.slice(3);
+  // Default: drain action. Allow `qualia-framework erp-flush show` / `clear` too.
+  const action = (args[0] && !args[0].startsWith("--")) ? args.shift() : "drain";
+  const r = spawnSync(process.execPath, [retryScript, action, ...args], {
+    stdio: "inherit",
+    shell: false,
+  });
+  process.exit(r.status || 0);
+}
+
 function cmdFlush() {
   const flushScript = path.join(CLAUDE_DIR, "bin", "knowledge-flush.js");
   if (!fs.existsSync(flushScript)) {
@@ -1073,6 +1096,7 @@ function cmdDoctor() {
     path.join(CLAUDE_DIR, "bin", "statusline.js"),
     path.join(CLAUDE_DIR, "bin", "knowledge.js"),
     path.join(CLAUDE_DIR, "bin", "knowledge-flush.js"),
+    path.join(CLAUDE_DIR, "bin", "erp-retry.js"),
     path.join(CLAUDE_DIR, "CLAUDE.md"),
     CONFIG_FILE,
   ];
@@ -1247,6 +1271,7 @@ function cmdHelp() {
   console.log(`    qualia-framework ${TEAL}agents${RESET}       Show per-agent run history (${DIM}--failed|--task ID|--phase N|prune --before${RESET})`);
   console.log(`    qualia-framework ${TEAL}set-erp-key${RESET}  Save/enable the ERP API key`);
   console.log(`    qualia-framework ${TEAL}erp-ping${RESET}     Verify ERP connectivity + API key`);
+  console.log(`    qualia-framework ${TEAL}erp-flush${RESET}    Retry queued ERP report uploads (${DIM}show|clear${RESET})`);
   console.log(`    qualia-framework ${TEAL}doctor${RESET}       Health-check the install (files, hooks, settings)`);
   console.log(`    qualia-framework ${TEAL}flush${RESET}        Promote daily-log → curated knowledge (memory layer)`);
   console.log("");
@@ -1312,6 +1337,10 @@ switch (cmd) {
   case "ping":
     cmdErpPing();
     break;
+  case "erp-flush":
+  case "erp-retry":
+    cmdErpFlush();
+    break;
   case "doctor":
   case "health":
   case "health-check":

package/bin/erp-retry.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+// ~/.claude/bin/erp-retry.js
+//
+// ERP report retry queue. /qualia-report enqueues a report here if the
+// inline 3-attempt-with-backoff upload fails. session-start.js drains the
+// queue quietly on the next Claude Code launch; `qualia-framework erp-flush`
+// drains it verbosely on demand.
+//
+// Why a queue: the prior v5.8 implementation told the user "$REPORT will
+// appear in ERP after retry" but had no retry mechanism — data was stranded
+// locally until the employee manually re-ran /qualia-report. Found by the
+// 2026-05-11 deep-research audit. This module makes the promise real.
+//
+// Idempotency: every enqueued item carries the Idempotency-Key header that
+// the original report attempt used. The ERP UPSERTs on
+// (project_id, client_report_id) and deduplicates Idempotency-Key for 24h,
+// so retry-of-a-just-succeeded item is safe.
+//
+// Hard rules:
+// - Never throw out the queue file on parse error — back it up and start fresh.
+// - Max 10 attempts per item before marking give_up=true (stops the cycle).
+// - 401/422 are permanent failures: keep the item but mark give_up=true so
+//   the user can see it and resolve manually (typically: fix the API key).
+// - The CLI invocation NEVER exits non-zero unless the queue file is unreadable —
+//   we don't want session-start.js to surface "hook error" red banners.
+//
+// Usage:
+//   node erp-retry.js                  # drain all (with default 3-attempt budget per item)
+//   node erp-retry.js --quiet          # no stdout unless errors
+//   node erp-retry.js --max=3          # drain at most 3 items this run
+//   node erp-retry.js --timeout=3000   # ms timeout per upload attempt
+//   node erp-retry.js show             # print queue contents, drain nothing
+//   node erp-retry.js clear            # delete the queue (use after manual fix)
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const https = require("https");
+const http = require("http");
+const urlLib = require("url");
+
+const HOME = os.homedir();
+const QUEUE_FILE = path.join(HOME, ".claude", ".erp-retry-queue.json");
+const API_KEY_FILE = path.join(HOME, ".claude", ".erp-api-key");
+const CONFIG_FILE = path.join(HOME, ".claude", ".qualia-config.json");
+
+const MAX_GIVE_UP_ATTEMPTS = 10;
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_ITEMS = 100;
+
+// ─── Args ───────────────────────────────────────────────
+const args = process.argv.slice(2);
+const ACTION = (args[0] && !args[0].startsWith("--")) ? args[0] : "drain";
+const QUIET = args.includes("--quiet");
+function flag(name, fallback) {
+  const found = args.find((a) => a.startsWith(`--${name}=`));
+  if (!found) return fallback;
+  const v = found.split("=", 2)[1];
+  const n = Number(v);
+  return Number.isFinite(n) ? n : fallback;
+}
+const MAX_ITEMS = flag("max", DEFAULT_MAX_ITEMS);
+const TIMEOUT_MS = flag("timeout", DEFAULT_TIMEOUT_MS);
+
+function log(msg) { if (!QUIET) process.stdout.write(msg + "\n"); }
+function logErr(msg) { process.stderr.write(msg + "\n"); }
+
+// ─── Queue I/O ──────────────────────────────────────────
+function readQueue() {
+  if (!fs.existsSync(QUEUE_FILE)) return { queue: [] };
+  try {
+    const raw = fs.readFileSync(QUEUE_FILE, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.queue)) return { queue: [] };
+    return parsed;
+  } catch (e) {
+    // Corrupt queue — back up and start fresh. Never silently destroy data.
+    const bak = `${QUEUE_FILE}.bak.${new Date().toISOString().replace(/[:.]/g, "-")}`;
+    try { fs.copyFileSync(QUEUE_FILE, bak); } catch {}
+    logErr(`erp-retry: queue file unparseable; backed up to ${bak} and starting fresh`);
+    return { queue: [] };
+  }
+}
+
+function writeQueue(data) {
+  const dir = path.dirname(QUEUE_FILE);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  // Atomic: write tmp, rename. Mode 0600 because the payload contains
+  // session notes that may reference internal project state.
+  const tmp = `${QUEUE_FILE}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+  try { fs.chmodSync(tmp, 0o600); } catch {}
+  fs.renameSync(tmp, QUEUE_FILE);
+}
+
+function enqueue({ client_report_id, idempotency_key, url, payload, last_error }) {
+  if (!client_report_id || !url || !payload) {
+    throw new Error("enqueue: client_report_id, url, payload are required");
+  }
+  const data = readQueue();
+  // Dedupe — if this report id is already queued, update the existing item
+  // instead of appending a duplicate.
+  const existing = data.queue.find((it) => it.client_report_id === client_report_id);
+  if (existing) {
+    existing.idempotency_key = idempotency_key || existing.idempotency_key;
+    existing.url = url;
+    existing.payload = payload;
+    existing.last_error = last_error || existing.last_error || "";
+    existing.attempts = existing.attempts || 0;
+    existing.give_up = false; // unblock a retry if user fixed the underlying issue
+    existing.enqueued_at = new Date().toISOString();
+  } else {
+    data.queue.push({
+      client_report_id,
+      idempotency_key: idempotency_key || "",
+      url,
+      payload,
+      enqueued_at: new Date().toISOString(),
+      attempts: 0,
+      last_error: last_error || "",
+      give_up: false,
+    });
+  }
+  writeQueue(data);
+}
+
+// ─── HTTP upload (native https — no curl bearer leak via /proc) ──
+function postOnce(item, apiKey) {
+  return new Promise((resolve) => {
+    let u;
+    try { u = urlLib.parse(item.url); } catch {
+      return resolve({ code: "—", body: "", error: "invalid url" });
+    }
+    const lib = u.protocol === "https:" ? https : http;
+    const headers = {
+      "Authorization": `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+      "Content-Length": Buffer.byteLength(item.payload),
+    };
+    if (item.idempotency_key) headers["Idempotency-Key"] = item.idempotency_key;
+    const req = lib.request({
+      method: "POST",
+      hostname: u.hostname,
+      port: u.port || (u.protocol === "https:" ? 443 : 80),
+      path: u.path,
+      headers,
+      timeout: TIMEOUT_MS,
+    }, (res) => {
+      let chunks = "";
+      res.setEncoding("utf8");
+      res.on("data", (c) => { chunks += c; });
+      res.on("end", () => resolve({ code: String(res.statusCode), body: chunks.trim(), error: null }));
+    });
+    req.on("error", (e) => resolve({ code: "—", body: "", error: e.message || "request failed" }));
+    req.on("timeout", () => { try { req.destroy(new Error("timeout")); } catch {} });
+    req.write(item.payload);
+    req.end();
+  });
+}
+
+function readApiKey() {
+  try { return fs.readFileSync(API_KEY_FILE, "utf8").trim(); } catch { return ""; }
+}
+
+function readConfig() {
+  try { return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8")); } catch { return {}; }
+}
+
+// ─── Actions ────────────────────────────────────────────
+async function actionDrain() {
+  const data = readQueue();
+  if (data.queue.length === 0) {
+    log("erp-retry: queue empty");
+    return { drained: 0, kept: 0, give_up: 0 };
+  }
+
+  const cfg = readConfig();
+  const erpEnabled = !cfg.erp || cfg.erp.enabled !== false;
+  if (!erpEnabled) {
+    log("erp-retry: ERP disabled in config; skipping drain (queue preserved)");
+    return { drained: 0, kept: data.queue.length, give_up: 0 };
+  }
+
+  const apiKey = readApiKey();
+  if (!apiKey) {
+    log("erp-retry: API key missing; skipping drain (queue preserved)");
+    return { drained: 0, kept: data.queue.length, give_up: 0 };
+  }
+
+  let drained = 0;
+  let give_up = 0;
+  const remaining = [];
+  let processed = 0;
+
+  for (const item of data.queue) {
+    // Already given up — keep but don't try.
+    if (item.give_up) {
+      remaining.push(item);
+      continue;
+    }
+    // Respect the per-run cap.
+    if (processed >= MAX_ITEMS) {
+      remaining.push(item);
+      continue;
+    }
+    processed++;
+
+    const result = await postOnce(item, apiKey);
+
+    if (result.code === "200") {
+      drained++;
+      log(`  ✓ uploaded ${item.client_report_id}`);
+      continue; // omit from remaining
+    }
+
+    item.attempts = (item.attempts || 0) + 1;
+    item.last_error = result.error
+      ? `network: ${result.error}`
+      : `HTTP ${result.code}${result.body ? `: ${result.body.slice(0, 200)}` : ""}`;
+
+    if (result.code === "401" || result.code === "422") {
+      // Permanent — surface to user.
+      item.give_up = true;
+      give_up++;
+      log(`  ✗ ${item.client_report_id} permanent fail (HTTP ${result.code}) — leaving in queue for manual review`);
+    } else if (item.attempts >= MAX_GIVE_UP_ATTEMPTS) {
+      item.give_up = true;
+      give_up++;
+      log(`  ✗ ${item.client_report_id} gave up after ${item.attempts} attempts (last: ${item.last_error})`);
+    } else {
+      log(`  · ${item.client_report_id} retry pending (attempt ${item.attempts}, last: ${item.last_error})`);
+    }
+    remaining.push(item);
+  }
+
+  writeQueue({ queue: remaining });
+
+  if (drained > 0 || give_up > 0 || !QUIET) {
+    log(`erp-retry: drained=${drained} kept=${remaining.length} give_up=${give_up}`);
+  }
+  return { drained, kept: remaining.length, give_up };
+}
+
+function actionShow() {
+  const data = readQueue();
+  if (data.queue.length === 0) {
+    log("queue empty");
+    return;
+  }
+  log(`${data.queue.length} item(s) in queue:`);
+  for (const item of data.queue) {
+    log(`  ${item.client_report_id}  enqueued=${item.enqueued_at}  attempts=${item.attempts || 0}${item.give_up ? "  GIVE_UP" : ""}`);
+    if (item.last_error) log(`    last_error: ${item.last_error}`);
+  }
+}
+
+function actionClear() {
+  if (!fs.existsSync(QUEUE_FILE)) {
+    log("queue already absent");
+    return;
+  }
+  // Back up rather than rm — destructive ops on user data deserve a recovery point.
+  const bak = `${QUEUE_FILE}.bak.${new Date().toISOString().replace(/[:.]/g, "-")}`;
+  try { fs.copyFileSync(QUEUE_FILE, bak); } catch {}
+  try { fs.unlinkSync(QUEUE_FILE); } catch {}
+  log(`queue cleared (backup at ${bak})`);
+}
+
+// ─── Export for in-process use (qualia-report skill enqueues directly) ──
+module.exports = { enqueue, readQueue, writeQueue };
+
+// ─── CLI entrypoint ─────────────────────────────────────
+if (require.main === module) {
+  (async () => {
+    try {
+      if (ACTION === "drain") await actionDrain();
+      else if (ACTION === "show") actionShow();
+      else if (ACTION === "clear") actionClear();
+      else {
+        logErr(`erp-retry: unknown action "${ACTION}". Use: drain | show | clear`);
+        process.exit(2);
+      }
+    } catch (e) {
+      logErr(`erp-retry: ${e && e.message ? e.message : e}`);
+      // Soft-fail so session-start.js never blocks.
+      process.exit(0);
+    }
+  })();
+}

package/bin/install.js

@@ -665,6 +665,12 @@ async function main() {
     );
     fs.chmodSync(path.join(binDest, "slop-detect.mjs"), 0o755);
     ok("slop-detect.mjs (anti-pattern scanner — runs pre-commit on frontend builds)");
+    copy(
+      path.join(FRAMEWORK_DIR, "bin", "erp-retry.js"),
+      path.join(binDest, "erp-retry.js")
+    );
+    fs.chmodSync(path.join(binDest, "erp-retry.js"), 0o755);
+    ok("erp-retry.js (ERP report retry queue — drained by session-start hook and erp-flush CLI)");
   } catch (e) {
     warn(`scripts — ${e.message}`);
   }

package/bin/state.js

@@ -329,7 +329,16 @@ function parseStateMd(content) {
 
 // ─── STATE.md Writer ─────────────────────────────────────
 function writeStateMd(s) {
-  const phaseFrac = Math.round(((s.phase - 1) / s.total_phases) * 100);
+  // Completed phases count toward progress. A phase counts as "done" once the
+  // state has advanced past `built` (i.e. status in verified/polished/shipped/handed_off).
+  // Without this adjustment, a 3-phase project shows 66% at completion and a
+  // 1-phase project shows 0% — the bar would never reach 100%.
+  const DONE_STATUSES = new Set(["verified", "polished", "shipped", "handed_off"]);
+  const currentDone = DONE_STATUSES.has(s.status) && s.verification !== "fail" ? 1 : 0;
+  const phaseFrac = Math.min(
+    100,
+    Math.round(((s.phase - 1 + currentDone) / s.total_phases) * 100)
+  );
   const filled = Math.round(phaseFrac / 10);
   const bar = "█".repeat(filled) + "░".repeat(10 - filled);
   const now = new Date().toISOString().split("T")[0];

package/docs/onboarding.html

@@ -505,8 +505,8 @@
       <div class="kit-group">
         <h4>Mid-flight design &amp; tests</h4>
         <dl>
-          <dt>/qualia-polish</dt><dd>Manual design pass on a component, route, or full app.</dd>
-          <dt>/qualia-polish-loop</dt><dd>Autonomous screenshot → score → fix loop until rubric passes.</dd>
+          <dt>/qualia-polish</dt><dd>Design pass — scope-adaptive: component, route, full app, redesign, critique, quick.</dd>
+          <dt>/qualia-polish --loop</dt><dd>Autonomous screenshot → score → fix loop until rubric passes.</dd>
           <dt>/qualia-test</dt><dd>Generate tests, run tests, or drive a feature TDD-style.</dd>
         </dl>
       </div>
@@ -521,8 +521,7 @@
       <div class="kit-group">
         <h4>Build something small</h4>
         <dl>
-          <dt>/qualia-quick</dt><dd>Trivial inline fix. One file, no spawn. Typo, config tweak.</dd>
-          <dt>/qualia-task</dt><dd>Single feature, fresh builder spawn, atomic commit. 1 to 5 files.</dd>
+          <dt>/qualia-feature</dt><dd>Auto-scoped: inline for trivia (typo, config tweak), fresh builder spawn for 1-5 file features. Refuses and routes to /qualia-plan when scope is phase-sized.</dd>
         </dl>
       </div>
       <div class="kit-group">
@@ -553,7 +552,6 @@
         <dl>
           <dt>/qualia-discuss</dt><dd>Without args: project-level non-technical discovery (mandatory at kickoff). With <code>N</code>: phase-level technical alignment with locked decisions and ADRs.</dd>
           <dt>/qualia-research</dt><dd>Deep-research a niche library or domain before planning a phase.</dd>
-          <dt>/qualia-prd</dt><dd>Synthesize the current conversation into a durable PRD document.</dd>
         </dl>
       </div>
       <div class="kit-group">

package/docs/playwright-loop-pilot-results.md

@@ -1,10 +1,12 @@
-# /qualia-polish-loop — Pilot results
+# /qualia-polish --loop — Pilot results
+
+> Historical pilot from v5.1.0 (when the command was `/qualia-polish-loop`). Paths updated to the current `skills/qualia-polish/` location after the v5.8.0 consolidation into the `--loop` flag.
 
 **Run date:** 2026-05-03
 **Framework version:** 5.1.0 (this commit)
 **Operator:** Claude Opus 4.7 (1M context), main session, autonomous build
 **Browser backend used:** Playwright cached chromium 1217 (`~/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome`) — auto-selected by `playwright-capture.mjs` after `import('playwright')` failed (no `playwright` npm package in the framework repo) and the cache lookup found a usable binary
-**Fixture server:** `python3 -m http.server 18080` against `skills/qualia-polish-loop/fixtures/`
+**Fixture server:** `python3 -m http.server 18080` against `skills/qualia-polish/fixtures/`
 **Captures:** `/tmp/qpl-pilot-1777778113/{scenario1,scenario2}/{mobile,tablet,desktop}-*.png`
 
 This pilot replaces an earlier draft that pre-dated the actual capture pipeline. The numbers below come from real runs of `playwright-capture.mjs` against the committed fixtures, not from architectural reasoning.
@@ -13,7 +15,7 @@ This pilot replaces an earlier draft that pre-dated the actual capture pipeline.
 
 ## Scenario 1 — Synthetic clean page
 
-**Fixture:** `skills/qualia-polish-loop/fixtures/clean.html` (170 lines). Fraunces + JetBrains Mono pair, OKLCH palette tinted toward 220° (cyan), asymmetric hero (`1.4fr / 1fr`), full-width with `clamp()` padding, varied work-grid (no card monotony), border-only headers, focus-visible rings, `prefers-reduced-motion` respected, 65ch line-length cap on prose.
+**Fixture:** `skills/qualia-polish/fixtures/clean.html` (170 lines). Fraunces + JetBrains Mono pair, OKLCH palette tinted toward 220° (cyan), asymmetric hero (`1.4fr / 1fr`), full-width with `clamp()` padding, varied work-grid (no card monotony), border-only headers, focus-visible rings, `prefers-reduced-motion` respected, 65ch line-length cap on prose.
 
 **Expected per spec:** SUCCESS in 1-2 iterations with all dims ≥ 4.
 
@@ -53,7 +55,7 @@ This pilot replaces an earlier draft that pre-dated the actual capture pipeline.
 
 ## Scenario 2 — Synthetic broken page
 
-**Fixture:** `skills/qualia-polish-loop/fixtures/broken.html` (115 lines). Deliberately shipped slop. Inter font as primary, pure `#fff` + `#000`, blue→purple linear-gradient hero, `background-clip: text` gradient on h1, three identical 1/3-width feature cards with `border-left: 4px solid #2563eb` side-stripes, "Get Started" + "Learn More" CTAs, `max-width: 1280px` container, `outline: none` on nav links without replacement.
+**Fixture:** `skills/qualia-polish/fixtures/broken.html` (115 lines). Deliberately shipped slop. Inter font as primary, pure `#fff` + `#000`, blue→purple linear-gradient hero, `background-clip: text` gradient on h1, three identical 1/3-width feature cards with `border-left: 4px solid #2563eb` side-stripes, "Get Started" + "Learn More" CTAs, `max-width: 1280px` container, `outline: none` on nav links without replacement.
 
 **Expected per spec:** Loop identifies all anti-patterns, fixes them, ends SUCCESS in 4-6 iterations.
 
@@ -110,7 +112,7 @@ This pilot replaces an earlier draft that pre-dated the actual capture pipeline.
 
 ```bash
 # Initialize a fresh state file
-node skills/qualia-polish-loop/scripts/loop.mjs init \
+node skills/qualia-polish/scripts/loop.mjs init \
   --state /tmp/.../qpl-kill.json --url http://localhost:3000 --max 8
 
 # Iteration 1: write an eval where typography==1 with a fixed issue fingerprint