qualia-framework 5.8.0 → 5.9.0

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

package/docs/research/2026-05-11-deep-research.md

@@ -0,0 +1,189 @@
+# Qualia Framework — Deep Research Audit
+
+**Date:** 2026-05-11
+**Version audited:** v5.8.0 (tip `387c422`)
+**Auditors:** 4 parallel investigators (surface health, ERP integration, token economy + personalization, workflow outcomes)
+**Method:** Grounded protocol — every claim carries `file:line` citation with quoted snippet.
+
+---
+
+## Headline verdict
+
+The framework is **structurally solid** but carries three real failure modes the user was right to suspect:
+
+1. **Documentation drift is the loudest silent failure.** Three user-facing surfaces (`rules/speed.md`, `templates/help.html`, `docs/onboarding.html`) still list `/qualia-quick`, `/qualia-task`, `/qualia-design`, `/qualia-prd`, `/qualia-polish-loop` — commands removed in v5.7/v5.8. A new hire following onboarding.html immediately hits dead ends.
+2. **ERP health is better than the user feared, but one promise is a lie.** After 3 failed upload attempts the message says "will appear in ERP after retry" — there is no retry mechanism. No queue, no cron, no session-start re-try. Data sits locally until the employee manually re-runs `/qualia-report`. The retry logic that DOES exist (1s/3s/9s backoff, 401/422 permanent-fail distinction) is correct.
+3. **Always-loaded substrate is ~2× larger than the "Pocock discipline" claim implies.** CLAUDE.md is genuinely 24 lines, but the 8 rules files (~480 lines) + 33 skill descriptions (~14.7 KB) total **~10,300 tokens** on every session start. ~5,400 of those are recoverable without losing functionality.
+
+Production-readiness score (framework as a product): **77 / 100**
+
+| Dimension | Score | One-line |
+|---|---:|---|
+| Surface honesty | 6/10 | Dead refs in 3 user-facing files |
+| ERP health | 7/10 | Real retry, false retry-promise, missing idempotency |
+| Token discipline | 6/10 | Real where claimed, but ~5.4K tokens of recoverable bloat |
+| Personalization | 3/10 | 4 employees are identical clones in the framework's eyes |
+| Workflow speed | 7/10 | Road works; kickoff has redundant questions, no fast path |
+| Verifier strictness | 7/10 | Strong protocol, INSUFFICIENT EVIDENCE silently treated as PASS |
+| Test coverage | 8/10 | State machine excellently tested, workflow loop untested |
+| Hooks (safety) | 9/10 | Genuinely well-engineered, zero token tax, real enforcement |
+
+---
+
+## CRITICAL findings (zero this round)
+
+None of the four audits surfaced a CRITICAL severity issue (security breach / data loss / auth bypass / crash on happy path). The framework's safety hooks (`branch-guard`, `git-guardrails`, `migration-guard`, `pre-deploy-gate`) and state-machine locking are real defenses.
+
+This is meaningful: the user's "I think this is very fucked up" suspicion about the ERP was wrong at the data-safety level — local commit always happens before upload, retry logic is correct, API key file is mode `0600`, no shell injection.
+
+---
+
+## HIGH findings (10 — fix before next minor)
+
+### Surface honesty
+
+**H1. `rules/speed.md:50-51` lists removed `/qualia-quick` + `/qualia-task` as active.**
+`speed.md` is read by users looking for shortcuts. Users will invoke commands that don't exist.
+
+**H2. `templates/help.html:377-379` shows `/qualia-quick`, `/qualia-task`, `/qualia-design`.**
+This is what `/qualia-help` opens in the browser. It's the canonical reference page.
+
+**H3. `docs/onboarding.html:509, 524, 525, 556` shows 4 removed commands.**
+This is the file the README explicitly recommends sending to new hires.
+
+### ERP
+
+**H4. `skills/qualia-report/SKILL.md:238` — "will appear in ERP after retry" is a lie.**
+There is no retry mechanism. No background queue, no cron, no session-start drain. Either build a retry queue at `~/.claude/.erp-retry-queue.json` and drain on session-start, OR change the message to honest "Re-run /qualia-report to retry."
+
+**H5. `skills/qualia-report/SKILL.md:220-222` — no `Idempotency-Key` header sent.**
+The ERP contract documents idempotency support with a 24h replay window (`docs/erp-contract.md:42-49`). The framework ignores this. The UPSERT on `(project_id, client_report_id)` covers most cases, but retries after a response-lost-mid-flight could double-count without the explicit header.
+
+**H6. `session_duration_minutes` documented in ERP contract example but never sent.**
+`docs/erp-contract.md:93` shows it; the payload builder at `skills/qualia-report/SKILL.md:192-205` never computes it. Trivial fix: `Math.round((Date.now() - new Date(t.session_started_at)) / 60000)`.
+
+### Workflow quality
+
+**H7. `agents/verifier.md:47` — 25-call tool budget + `skills/qualia-verify/SKILL.md` doesn't block on INSUFFICIENT EVIDENCE.**
+The verifier is told "mark unchecked criteria as INSUFFICIENT EVIDENCE" when budget exhausts. The orchestrator does not grep for that string before declaring PASS. Phases with 8+ tasks can pass verification with criteria literally not checked. **This is the #1 false-pass vector.**
+
+**H8. `/qualia-new` has 15-21+ user questions before any code is written.**
+14 discovery + 1 design vibe + 1 client + 5 PRODUCT.md + N feature scoping. The PRODUCT.md questions at `skills/qualia-new/SKILL.md:163-169` overlap with discovery questions 2-5. Demos hit ~15 interactions despite the "8 questions for demos" framing.
+
+### Personalization
+
+**H9. All 4 employees (Hasan, Moayad, Rama, Sally) have identical role descriptions.**
+`bin/install.js:31-57` — every EMPLOYEE entry has the description "Developer. Feature branches only. Cannot push to main." No stack expertise, seniority, specialization. The framework cannot adapt explanation depth, task assignment, or review style per developer.
+
+**H10. `architecture.md` is always-loaded but explicitly says "Do not auto-load this on quick fixes."**
+`rules/architecture.md` is 125 lines (~1,560 tokens). It lives in `~/.claude/rules/` where Claude Code auto-loads everything. The file itself contradicts its location.
+
+---
+
+## MEDIUM findings (12 — fix this quarter)
+
+| # | Where | What |
+|---|---|---|
+| M1 | `bin/state.js:332` | Progress bar formula `(phase-1)/total_phases` — completed project shows 66%, never 100% |
+| M2 | `agents/builder.md:155`, `agents/planner.md:147`, `agents/research-synthesizer.md:91` | "likely", "probably" — hedging language the grounding protocol explicitly bans |
+| M3 | `bin/state.js:375-376` | `polished → shipped` mandatory; no skip for API-only / backend-only projects |
+| M4 | `skills/zoho-workflow/` | Completely unreferenced — orphan skill |
+| M5 | `tests/skills.test.sh` | Tests structure, not behavior — no integration test for the plan→build→verify loop |
+| M6 | `agents/plan-checker.md:83` | "Any shared file = wave conflict" forces unnecessary serialization (no read-only-overlap distinction) |
+| M7 | `agents/plan-checker.md:173-179` | Scope-reduction Rule 10 substring-matches "v1", "basic version" — false REVISE on legit plans |
+| M8 | `agents/verifier.md:315-317` + `:356-362` | Design rubric fires full 8-dim on any `.tsx` file presence — backend-heavy phases get disproportionate design scrutiny |
+| M9 | `bin/cli.js:874-888` | `erp-ping` sends synthetic payload — does not validate current schema |
+| M10 | `skills/qualia-report/SKILL.md:197` | `framework_version` reads from config snapshot at install time — stale after `npm update` |
+| M11 | `skills/qualia-new/SKILL.md:163-169` | PRODUCT.md questions duplicate discovery questions 2-5 |
+| M12 | `skills/qualia/SKILL.md:38-55` | Router has no row for "I want a one-off change outside the Road" — users must already know `/qualia-feature` exists |
+
+---
+
+## LOW findings (5)
+
+- L1. `hooks/pre-compact.js:80-81` — default `--no-verify` + `--no-gpg-sign` (configurable, documented, but silent default)
+- L2. `docs/playwright-loop-pilot-results.md:7,16,56,113` — references the renamed `skills/qualia-polish-loop/` path
+- L3. `skills/qualia-report/SKILL.md:152` — error table shows the old `set-erp-key <key>` positional syntax (CLI now requires piped)
+- L4. `bin/state.js:130` — trace probabilistic pruning (1% chance) may let `.qualia-traces/` grow unnecessarily on heavy installs
+- L5. `agents/visual-evaluator.md:91` — `likely_file` (as JSON field name, borderline)
+
+---
+
+## Cross-cutting patterns
+
+### Pattern 1: Surface drift outpaces test coverage
+
+`tests/skills.test.sh` validates that every SKILL.md has the right frontmatter. It does NOT validate that command references inside SKILL.md, rules/, docs/, templates/ point to skills that still exist. Three v5.7/v5.8 removals slipped through because the test surface is structural, not referential.
+
+**Fix:** Add `tests/refs.test.sh` that greps every `.md` and `.html` for `/qualia-{name}` and asserts each name has a matching `skills/qualia-{name}/SKILL.md`.
+
+### Pattern 2: The framework is more disciplined than its tooling enforces
+
+CLAUDE.md is genuinely lean. Design substrate was correctly moved off the always-loaded path. Hooks enforce deterministically. But:
+
+- `rules/architecture.md` lives where it auto-loads despite its own warning
+- Skill descriptions accumulate flavor text ("Karpathy-style", "v5.3 from Matt Pocock's...") on top of trigger phrases — every change invalidates the cache prefix
+- 8 rules files always-load when 3 are sufficient for most sessions
+
+**Fix:** A `tests/budget.test.sh` that asserts total always-loaded substrate stays under ~6,000 tokens.
+
+### Pattern 3: The verifier knows what to check but can't always afford to check it
+
+The 3-level verification (Truths / Artifacts / Wiring) is the right abstraction. The 25-call budget makes it un-affordable on phases with 8+ tasks. INSUFFICIENT EVIDENCE is the escape hatch, but the orchestrator doesn't punish it. So the verifier silently approves under-verified phases.
+
+**Fix:** Budget = `max(25, tasks * 5)`. AND: any INSUFFICIENT EVIDENCE in the verification file → verdict downgraded to FAIL.
+
+### Pattern 4: Personalization is structurally absent
+
+There are 4 distinct humans (Hasan, Moayad, Rama, Sally) who get an identical one-sentence description. The daily-log, knowledge layer, learned-patterns, and commit history all contain per-user signal that is collected and never read for personalization.
+
+**Fix:** Per-employee profile file under `~/.claude/team/{code}.md`, injected into CLAUDE.md template at install time. Auto-derived from daily logs via a `/qualia-flush` extension.
+
+---
+
+## Top 10 fixes ranked by ROI
+
+1. **Find-and-replace the 6 dead command references in `speed.md`, `help.html`, `onboarding.html`** — 15 min. Eliminates every user-facing dead end.
+2. **Add INSUFFICIENT EVIDENCE blocker to `qualia-verify`** — 20 min. Eliminates the #1 false-pass vector.
+3. **Stop lying about retry: either build the queue or change the message** — 30 min for the message change, ~3 hours for the queue.
+4. **Send `Idempotency-Key` + `session_duration_minutes` in ERP payload** — 20 min. Completes the documented contract.
+5. **Move `architecture.md` to `~/.claude/qualia-substrate/` (lazy-load)** — 10 min. Saves ~1,560 tokens per session.
+6. **Trim skill descriptions to trigger-phrases-only** — 1 hour. Saves ~1,500 tokens per session + improves cache stability.
+7. **Per-employee profile files (`team/{code}.md`)** — 2 hours. Transforms personalization from 0 to material.
+8. **Scale verifier budget to `max(25, tasks*5)`** — 5 min. Eliminates INSUFFICIENT EVIDENCE on large phases.
+9. **Merge PRODUCT.md questions into the discovery interview** — 30 min. Cuts ~3 questions from every kickoff.
+10. **Add `tests/refs.test.sh`** — 45 min. Prevents the next surface-drift incident.
+
+**Total effort for all 10:** ~8-10 hours.
+**Effort-weighted impact:** removes every found false-pass vector, every documented dead-link, ~3K of recoverable tokens, the framework's biggest UX papercut (personalization), and the largest invisible quality risk (INSUFFICIENT EVIDENCE silently passing).
+
+---
+
+## What the framework does WELL (honest acknowledgement)
+
+These are not patronizing — they came up across all four audits.
+
+1. **State machine** (`bin/state.js`). 57 behavioral tests. Atomic dual-file writes. File-based locking with stale detection. Crash-recovery journaling. Gap-cycle circuit breaker with configurable limit. Schema validation + repair. This is real engineering.
+2. **Hook architecture.** Pure Node.js (Windows-safe). Zero model-token tax (deterministic enforcement, not instructional). Real protections: service_role leak scan, force-push-to-main block (role-aware), migration safety, Vercel account guard, env-empty guard.
+3. **Verifier abstraction** (Truths / Artifacts / Wiring). Most AI coding tools check "did the task run." The Qualia verifier checks "is the artifact substantive, is it imported, is it called." The stub-detection patterns are operational learning, not theory.
+4. **Polish-loop kill-switch.** Fingerprint regression detection + budget cap. Real engineering against the known infinite-loop failure mode of vision-model feedback loops.
+5. **ERP security hardening.** Native `https.request` instead of curl (no bearer in `/proc/cmdline`). API key mode `0600`. Refuses positional CLI args. Env-var passing in payload builder (no shell injection). Atomic tmp+rename writes.
+
+---
+
+## Resources & references
+
+- All findings cite specific files. Original investigator outputs from this audit are not committed (held in conversation context).
+- Grounding protocol: `/home/qualia-new/.claude/rules/grounding.md`
+- Severity criteria: same file.
+- Pocock instruction-budget pattern: referenced in README:8.
+- ERP contract spec: `docs/erp-contract.md` (this file exists and was used by the ERP-integration audit).
+
+---
+
+## Open questions for the user
+
+1. **The retry-queue approach for ERP** — would you prefer (a) an honest message change ("re-run to retry"), (b) a queue file drained on session-start, or (c) a cron job? Each has different operational characteristics.
+2. **Personalization depth** — willing to spend an afternoon writing 4 profile files for Hasan/Moayad/Rama/Sally? Or want this auto-derived from daily logs over time?
+3. **Token cuts vs cache stability** — some of the cuts (e.g. trimming skill descriptions) will invalidate prompt caches for one cycle. Worth it once, or keep stable?
+4. **The 14-question discovery interview** — keep depth at the kickoff cost, or shave 4-5 questions and accept slightly fuzzier project framing?

package/hooks/session-start.js

@@ -26,6 +26,8 @@ const STATE_FILE = path.join(".planning", "STATE.md");
 const CONTINUE_HERE = ".continue-here.md";
 const NOTIF_FILE = path.join(HOME, ".claude", ".qualia-update-available.json");
 const HEALTH_FILE = path.join(HOME, ".claude", ".qualia-install-health.json");
+const ERP_RETRY = path.join(HOME, ".claude", "bin", "erp-retry.js");
+const ERP_QUEUE = path.join(HOME, ".claude", ".erp-retry-queue.json");
 
 // Critical files referenced by skills via @-import. If any are missing, skills
 // silently get empty context and produce ungrounded output. We spot-check these
@@ -115,6 +117,21 @@ function fallbackText() {
   }
 }
 
+function maybeDrainErpQueue() {
+  // Fire-and-forget drain of any reports stranded from a prior /qualia-report
+  // upload failure. Cheap fast-path: only spawn if the queue file exists and
+  // erp-retry.js is installed. Quiet mode + small max so we never block the
+  // session-start critical path. The script itself exits 0 even on internal
+  // errors — see erp-retry.js's CLI tail.
+  try {
+    if (!fs.existsSync(ERP_QUEUE) || !fs.existsSync(ERP_RETRY)) return;
+    spawnSync(process.execPath, [ERP_RETRY, "drain", "--quiet", "--max=5", "--timeout=2500"], {
+      stdio: "ignore",
+      timeout: 8000,
+    });
+  } catch {}
+}
+
 function maybeRenderUpdateBanner() {
   // EMPLOYEE-only sticky banner. auto-update.js writes NOTIF_FILE when a new
   // version is detected; we render it every session until the user actually
@@ -144,6 +161,7 @@ function renderHealthWarning(missing) {
 
 try {
   maybeRenderUpdateBanner();
+  maybeDrainErpQueue();
 
   const healthMissing = checkInstallHealth();
   if (healthMissing) renderHealthWarning(healthMissing);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -31,7 +31,8 @@
     "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 && bash tests/skills.test.sh && bash tests/slop-detect.test.sh"
+    "test:refs": "bash tests/refs.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/refs.test.sh && bash tests/slop-detect.test.sh"
   },
   "files": [
     "bin/",

package/rules/speed.md

@@ -47,8 +47,7 @@ The pattern: **on-demand by default; always-on only when the data is irreducibly
 
 When a Qualia command exists for the situation, use it — don't reinvent:
 - `/qualia` — what's my next step?
-- `/qualia-quick` — small inline fix, no plan, no spawn
-- `/qualia-task` — single focused task, fresh builder spawn, atomic commit
+- `/qualia-feature` — single feature, auto-scoped: inline for trivia, fresh builder spawn for 1-5 file features
 - `/qualia-ship` — full deploy pipeline (quality gates → commit → deploy → verify)
 - `/qualia-review` — production audit
 - `/qualia-pause` — save context before clearing the conversation

package/skills/qualia-report/SKILL.md

@@ -168,6 +168,17 @@ REPORT_FILE=".planning/reports/report-{date}.md"
 SUBMITTED_BY=$(git config user.name || echo "unknown")
 SUBMITTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 
+# Idempotency key — deterministic per (client_report_id, submitted_at). A retry
+# of the same shift report carries the same key, so the ERP can dedupe at the
+# header level in addition to the UPSERT on (project_id, client_report_id).
+IDEMPOTENCY_KEY=$(node -e "
+  const c=require('crypto');
+  const seed='$CLIENT_REPORT_ID|$SUBMITTED_AT|'+require('path').basename(process.cwd());
+  // RFC 4122 v5-style: deterministic UUID from sha1 of the seed
+  const h=c.createHash('sha1').update(seed).digest('hex');
+  console.log([h.slice(0,8),h.slice(8,12),'5'+h.slice(13,16),'8'+h.slice(17,20),h.slice(20,32)].join('-'));
+")
+
 # Guard: API key required for upload (otherwise curl posts an empty bearer)
 if [ "$ERP_ENABLED" = "true" ] && [ -z "$API_KEY" ] && [ "$DRY_RUN" != "true" ]; then
   node ~/.claude/bin/qualia-ui.js warn "ERP API key missing (~/.claude/.erp-api-key). Run: qualia-framework set-erp-key <key>"
@@ -189,6 +200,17 @@ PAYLOAD=$(
     const commits=[];try{const r=spawnSync('git',['log','--oneline','--since=8 hours ago','--format=%h'],{encoding:'utf8',timeout:3000});if(r.stdout)commits.push(...r.stdout.trim().split('\n').filter(Boolean));}catch{}
     const gitRemote=t.git_remote||git(['config','--get','remote.origin.url']);
     const projectKey=t.project_id||repoSlug(gitRemote)||require('path').basename(process.cwd());
+    // Session duration: minutes from session_started_at to submitted_at. The ERP's
+    // example payload (docs/erp-contract.md:93) includes this; without it the ERP
+    // can't compute shift-length analytics without parsing notes.
+    let sessionDurationMinutes=0;
+    if(t.session_started_at){
+      const startMs=Date.parse(t.session_started_at);
+      const endMs=Date.parse(process.env.SUBMITTED_AT)||Date.now();
+      if(!Number.isNaN(startMs)&&endMs>startMs){
+        sessionDurationMinutes=Math.round((endMs-startMs)/60000);
+      }
+    }
     console.log(JSON.stringify({
       project:t.project||require('path').basename(process.cwd()),
       project_id:projectKey,team_id:t.team_id||'qualia-solutions',git_remote:gitRemote,
@@ -200,6 +222,7 @@ PAYLOAD=$(
       gap_cycles:(t.gap_cycles||{})[String(t.phase)]||0,build_count:t.build_count||0,
       deploy_count:t.deploy_count||0,deployed_url:t.deployed_url||'',
       session_started_at:t.session_started_at||'',last_pushed_at:t.last_pushed_at||'',
+      session_duration_minutes:sessionDurationMinutes,
       lifetime:t.lifetime||{},commits:commits,notes:notes,
       submitted_by:process.env.SUBMITTED_BY||'unknown',submitted_at:process.env.SUBMITTED_AT
     }));
@@ -214,11 +237,15 @@ if [ "$DRY_RUN" = "true" ]; then
   exit 0
 fi
 
-# Upload — 3 attempts with 1s/3s/9s backoff
+# Upload — 3 attempts with 1s/3s/9s backoff.
+# Idempotency-Key header carries a deterministic UUID per (client_report_id, submitted_at)
+# so the ERP can dedupe at the request level in addition to the UPSERT key on the body.
+# Documented in docs/erp-contract.md:42-49 with a 24h replay window.
 if [ "$ERP_ENABLED" = "true" ]; then
   for ATTEMPT in 1 2 3; do
     RESPONSE=$(curl -sS -X POST "$ERP_URL/api/v1/reports" \
       -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+      -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
       -d "$PAYLOAD" --max-time 10 -w "\n__HTTP__%{http_code}" 2>&1)
     HTTP_CODE=$(echo "$RESPONSE" | grep -o "__HTTP__[0-9]*" | sed 's/__HTTP__//')
     BODY=$(echo "$RESPONSE" | sed 's/__HTTP__[0-9]*//g')
@@ -235,7 +262,42 @@ if [ "$ERP_ENABLED" = "true" ]; then
     fi
     [ $ATTEMPT -lt 3 ] && { SLEEP=$((1 * 3 ** (ATTEMPT - 1))); node ~/.claude/bin/qualia-ui.js warn "Attempt $ATTEMPT failed (HTTP ${HTTP_CODE:-timeout}), retrying in ${SLEEP}s..."; sleep $SLEEP; }
   done
-  [ "$ATTEMPT" = "3" ] && [ "$HTTP_CODE" != "200" ] && node ~/.claude/bin/qualia-ui.js warn "ERP upload failed after 3 attempts. $CLIENT_REPORT_ID is committed locally; will appear in ERP after retry."
+
+  # If all 3 in-process attempts failed, enqueue the report into the persistent
+  # retry queue (~/.claude/.erp-retry-queue.json). session-start.js drains it on
+  # the next Claude Code launch; `qualia-framework erp-flush` drains it on demand.
+  # This replaces the prior "will appear after retry" message which was a lie —
+  # no retry mechanism existed before v5.9.
+  if [ "$ATTEMPT" = "3" ] && [ "$HTTP_CODE" != "200" ]; then
+    LAST_ERR="HTTP ${HTTP_CODE:-timeout}"
+    if [ -n "$BODY" ]; then LAST_ERR="$LAST_ERR: $(echo "$BODY" | head -c 200)"; fi
+    PAYLOAD="$PAYLOAD" \
+    CLIENT_REPORT_ID="$CLIENT_REPORT_ID" \
+    IDEMPOTENCY_KEY="$IDEMPOTENCY_KEY" \
+    ERP_URL="$ERP_URL" \
+    LAST_ERR="$LAST_ERR" \
+    node -e "
+      try {
+        const {enqueue} = require(require('os').homedir() + '/.claude/bin/erp-retry.js');
+        enqueue({
+          client_report_id: process.env.CLIENT_REPORT_ID,
+          idempotency_key: process.env.IDEMPOTENCY_KEY,
+          url: process.env.ERP_URL + '/api/v1/reports',
+          payload: process.env.PAYLOAD,
+          last_error: process.env.LAST_ERR,
+        });
+        process.stdout.write('enqueued');
+      } catch (e) {
+        process.stderr.write('enqueue failed: ' + (e.message || e));
+        process.exit(1);
+      }
+    " 2>/dev/null && {
+      node ~/.claude/bin/qualia-ui.js warn "ERP upload failed after 3 attempts — $CLIENT_REPORT_ID enqueued for auto-retry on next session"
+      node ~/.claude/bin/qualia-ui.js info "Drain manually with: qualia-framework erp-flush"
+    } || {
+      node ~/.claude/bin/qualia-ui.js warn "ERP upload failed after 3 attempts AND queue enqueue failed. $CLIENT_REPORT_ID is committed locally — re-run /qualia-report later to retry."
+    }
+  fi
 fi
 
 [ "$ERP_ENABLED" != "true" ] && node ~/.claude/bin/qualia-ui.js info "ERP upload skipped (disabled). $CLIENT_REPORT_ID committed locally."

package/skills/qualia-verify/SKILL.md

@@ -104,6 +104,22 @@ Append '## Adversarial Findings' to verification file. Empty section fine if not
 
 Findings merge into main report. Union PASS/FAIL: either pass found CRITICAL/HIGH → phase FAIL.
 
+### 2d. INSUFFICIENT EVIDENCE downgrade (mandatory)
+
+The verifier marks criteria it could not check (budget exhaustion, missing context) as `INSUFFICIENT EVIDENCE`. The orchestrator treats those as silent PASS unless explicitly downgraded — that's the #1 false-pass vector. Grep the verification file before declaring PASS:
+
+```bash
+IE_COUNT=$(grep -c "INSUFFICIENT EVIDENCE" .planning/phase-{N}-verification.md 2>/dev/null || echo 0)
+if [ "$IE_COUNT" -gt 0 ]; then
+  node ~/.claude/bin/qualia-ui.js warn "${IE_COUNT} criteria marked INSUFFICIENT EVIDENCE — downgrading verdict to FAIL"
+  # Rewrite the verdict line in-place
+  sed -i 's/^result: PASS$/result: FAIL/' .planning/phase-{N}-verification.md
+  sed -i 's/^## Verdict$/## Verdict\n\n**Downgraded to FAIL:** '"${IE_COUNT}"' criteria left unchecked. Re-run with larger budget (`max(25, tasks*5)` already applied) or simplify the phase plan./' .planning/phase-{N}-verification.md
+fi
+```
+
+The same check runs after the adversarial pass if it executed.
+
 ### 3. Present Results
 
 Read verification report. Present:

package/templates/help.html

@@ -374,9 +374,8 @@
       <h3>Quick Paths</h3>
       <p class="cmd-group-note">Lightweight alternatives when the full road is overkill.</p>
       <div class="commands">
-        <div class="cmd"><span class="cmd-name">/qualia-quick</span><span class="cmd-desc">Fast path for small tasks &mdash; bug fixes, tweaks, hot fixes. Skips full phase planning.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-task</span><span class="cmd-desc">Build a single task &mdash; more structured than /qualia-quick, lighter than /qualia-build. Spawns a fresh builder agent for one focused task.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-design</span><span class="cmd-desc">One-shot design transformation &mdash; critiques, fixes, polishes, hardens, makes responsive. No reports, no choices, just makes it professional.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-feature</span><span class="cmd-desc">Auto-scoped single-feature build. Inline for trivia (typo, config), fresh builder spawn for 1-5 file features. Refuses and routes to /qualia-plan for phase-sized work. Flags: --force-spawn, --force-inline.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-polish</span><span class="cmd-desc">Design pass, scope-adaptive &mdash; component, route, full app, redesign, critique, quick. Add --loop for the autonomous screenshot &rarr; score &rarr; fix loop.</span></div>
       </div>
     </div>
 

package/tests/bin.test.sh

@@ -719,18 +719,36 @@ else
   fail_case "research-synthesizer missing model frontmatter"
 fi
 
-# 64. Other agents do NOT have model frontmatter (conservative matrix)
-SAFE_AGENTS=("planner.md" "builder.md" "verifier.md" "plan-checker.md")
+# 64. v5.9 model tiering: structured agents (verifier, plan-checker, roadmapper,
+# qa-browser) use Sonnet. Real-reasoning agents (planner, builder, researcher,
+# visual-evaluator) keep inherited Opus.
+SONNET_AGENTS=("verifier.md" "plan-checker.md" "roadmapper.md" "qa-browser.md")
+OPUS_AGENTS=("planner.md" "builder.md" "researcher.md" "visual-evaluator.md")
+
+ALL_OK=1
+for a in "${SONNET_AGENTS[@]}"; do
+  if ! grep -q '^model: sonnet$' "$TMP/.claude/agents/$a" 2>/dev/null; then
+    ALL_OK=0
+    echo "    missing 'model: sonnet' in $a"
+  fi
+done
+if [ "$ALL_OK" = "1" ]; then
+  pass "structured agents (verifier/plan-checker/roadmapper/qa-browser) use sonnet (v5.9 tiering)"
+else
+  fail_case "v5.9 sonnet-tier agent has wrong model frontmatter"
+fi
+
 ALL_OK=1
-for a in "${SAFE_AGENTS[@]}"; do
+for a in "${OPUS_AGENTS[@]}"; do
   if grep -q '^model: ' "$TMP/.claude/agents/$a" 2>/dev/null; then
     ALL_OK=0
+    echo "    unexpected 'model:' in $a (should inherit Opus)"
   fi
 done
 if [ "$ALL_OK" = "1" ]; then
-  pass "high-stakes agents (planner/builder/verifier/plan-checker) keep default model"
+  pass "reasoning agents (planner/builder/researcher/visual-evaluator) inherit Opus"
 else
-  fail_case "high-stakes agent has unexpected model frontmatter"
+  fail_case "Opus-tier agent has unexpected model frontmatter"
 fi
 
 echo ""

package/tests/refs.test.sh

@@ -0,0 +1,146 @@
+#!/bin/bash
+# Qualia Framework — surface-drift guard
+# Greps every active surface for backtick-quoted /qualia-{name} command references.
+# Asserts each name has a matching skills/qualia-{name}/SKILL.md.
+#
+# Why: v5.7 + v5.8 removed /qualia-quick, /qualia-task, /qualia-prd, /qualia-design,
+# /qualia-polish-loop. Three user-facing files (rules/speed.md, templates/help.html,
+# docs/onboarding.html) still pointed at the removed commands. New hires hit dead
+# ends. This test fails when that happens again.
+#
+# Scoping rules:
+# - Only matches references quoted in markdown backticks (`/qualia-foo`) or shown
+#   as a slash-command at line start. Bare path refs (/qualia-templates/,
+#   /qualia-ui.js) are excluded — they're directories or scripts, not commands.
+# - Historical surfaces (docs/reviews/, docs/research/, CHANGELOG) are excluded —
+#   they intentionally describe past states.
+# - Migration mentions on active surfaces (README/guide describing v5.7 removals)
+#   are excluded via a context prefix check.
+#
+# Run: bash tests/refs.test.sh
+
+FRAMEWORK_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SKILLS_DIR="$FRAMEWORK_ROOT/skills"
+
+PASS=0
+FAIL=0
+
+pass() {
+  echo "  ✓ $1"
+  PASS=$((PASS + 1))
+}
+
+fail_case() {
+  echo "  ✗ $1"
+  echo "    $2"
+  FAIL=$((FAIL + 1))
+}
+
+# Files we never scan — historical records, backups, vendored deps.
+EXCLUDE_REGEX='/docs/reviews/|/docs/research/|/docs/playwright-loop-pilot-results\.md$|/CHANGELOG\.md$|\.bak\.|\.git/|/node_modules/|/\.continue-here\.md$'
+
+# When a `/qualia-foo` ref appears AFTER one of these context tokens on the same line,
+# it's a migration-explainer ("Replaces /qualia-quick" / "deprecated in v5.7"), not
+# a live command reference. Treat it as exempt.
+MIGRATION_CONTEXT_REGEX='Replaces|Removed|removed in|consolidated|deprecated|renamed|former|previously|was the|now the|now\s+`?/qualia|absorbed|superseded|legacy|migrated|after\s+`?/qualia.*-(quick|task|prd|design|polish-loop)'
+
+ACTIVE_DIRS=(
+  "$FRAMEWORK_ROOT/rules"
+  "$FRAMEWORK_ROOT/skills"
+  "$FRAMEWORK_ROOT/agents"
+  "$FRAMEWORK_ROOT/hooks"
+  "$FRAMEWORK_ROOT/templates"
+)
+
+ACTIVE_FILES=(
+  "$FRAMEWORK_ROOT/README.md"
+  "$FRAMEWORK_ROOT/guide.md"
+  "$FRAMEWORK_ROOT/CLAUDE.md"
+  "$FRAMEWORK_ROOT/AGENTS.md"
+  "$FRAMEWORK_ROOT/docs/onboarding.html"
+)
+
+echo "refs.test.sh — surface-drift guard (active /qualia-* references must point at shipped skills)"
+echo ""
+
+SCAN_FILES=$(
+  {
+    for d in "${ACTIVE_DIRS[@]}"; do
+      [ -d "$d" ] && find "$d" -type f \( -name "*.md" -o -name "*.html" \)
+    done
+    for f in "${ACTIVE_FILES[@]}"; do
+      [ -f "$f" ] && echo "$f"
+    done
+  } | grep -Ev "$EXCLUDE_REGEX" | sort -u
+)
+
+# Extract backtick-quoted command refs only. Two patterns:
+#   1. `/qualia-foo`       — backticked, the canonical command-doc style
+#   2. <dt>/qualia-foo</dt> — HTML help/onboarding pages
+# We capture name + file:line so we can show context per failure.
+declare -A SEEN_REFS
+declare -A REF_LOCATIONS
+
+while IFS= read -r file; do
+  # Pattern A: backtick-quoted commands. Allow trailing flag/word but only capture base name.
+  while IFS=: read -r path lineno line; do
+    [ -z "$line" ] && continue
+    # Skip migration-context lines.
+    if echo "$line" | grep -qE "$MIGRATION_CONTEXT_REGEX"; then
+      continue
+    fi
+    # Extract every backticked /qualia-foo on this line.
+    matches=$(echo "$line" | grep -oE '`/qualia(-[a-z]+){0,3}`' | sed 's/^`//; s/`$//')
+    for ref in $matches; do
+      SEEN_REFS["$ref"]=1
+      REF_LOCATIONS["$ref"]="${REF_LOCATIONS[$ref]:+${REF_LOCATIONS[$ref]}, }$(basename "$path"):$lineno"
+    done
+  done < <(grep -nE '`/qualia(-[a-z]+){0,3}`' "$file" 2>/dev/null)
+
+  # Pattern B: HTML <dt>/qualia-foo</dt>.
+  while IFS=: read -r path lineno line; do
+    [ -z "$line" ] && continue
+    if echo "$line" | grep -qE "$MIGRATION_CONTEXT_REGEX"; then
+      continue
+    fi
+    matches=$(echo "$line" | grep -oE '<dt>/qualia(-[a-z]+){0,3}( [^<]*)?</dt>' | sed -E 's|<dt>(/qualia(-[a-z]+){0,3}).*|\1|')
+    for ref in $matches; do
+      SEEN_REFS["$ref"]=1
+      REF_LOCATIONS["$ref"]="${REF_LOCATIONS[$ref]:+${REF_LOCATIONS[$ref]}, }$(basename "$path"):$lineno"
+    done
+  done < <(grep -nE '<dt>/qualia' "$file" 2>/dev/null)
+done <<<"$SCAN_FILES"
+
+if [ ${#SEEN_REFS[@]} -eq 0 ]; then
+  fail_case "scan" "no backticked /qualia-* references found across active surfaces (scanner broken?)"
+  echo ""
+  echo "Results: $PASS passed, $FAIL failed"
+  exit 1
+fi
+
+# Sort refs for deterministic output.
+for ref in $(printf '%s\n' "${!SEEN_REFS[@]}" | sort); do
+  name="${ref#/}"
+  skill_dir="$SKILLS_DIR/$name"
+  locations="${REF_LOCATIONS[$ref]}"
+  if [ -d "$skill_dir" ] && [ -f "$skill_dir/SKILL.md" ]; then
+    pass "$ref → skills/$name/SKILL.md"
+    continue
+  fi
+  fail_case "$ref" "no skills/$name/SKILL.md — referenced by: $locations"
+done
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+
+if [ "$FAIL" -gt 0 ]; then
+  echo ""
+  echo "Surface drift detected. To fix one of:"
+  echo "  1. Restore the missing skill at skills/<name>/SKILL.md"
+  echo "  2. Update the offending file to point at the replacement command"
+  echo "  3. Reframe the mention as a migration note (this test skips lines containing"
+  echo "     'Replaces', 'consolidated', 'deprecated', 'now', 'former', 'superseded', etc.)"
+  exit 1
+fi
+
+exit 0