qualia-framework 5.5.0 → 5.9.0

package/README.md

@@ -1,14 +1,18 @@
-# Qualia Framework v5.3
+# Qualia Framework v5.8
 
 A harness engineering framework for [Claude Code](https://claude.ai/code). It installs into `~/.claude/` and wraps your AI-assisted development workflow with structured planning, execution, verification, and deployment gates.
 
-It is not an application framework like Rails or Next.js. It doesn't generate code, run servers, or process data. It's an opinionated workflow layer that tells Claude how to plan, build, and verify your projects — end-to-end, from "tell me what you want to make" to "here's the handoff doc for your client."
+It is not an application framework like Rails or Next.js. It doesn't generate code, run servers, or process data. It's an opinionated workflow layer that tells Claude how to plan, build, and verify your projects end-to-end, from "tell me what you want to make" to "here's the handoff doc for your client."
 
-**The v5 line in three releases:**
-- **v5.0** — alignment discipline. CONTEXT.md domain glossary, decisions/ ADRs, `/qualia-zoom`, `/qualia-issues`, `/qualia-triage`, slim CLAUDE.md per Matt Pocock's instruction-budget rule, insights-driven hooks (Vercel account, empty env-var, Supabase destructive guards).
-- **v5.1** — `/qualia-polish-loop` (autonomous visual-polish loop: screenshots a URL at three viewports, scores 8 design dimensions with vision, fixes top issues, loops until pass or kill-switch); multi-target installer (Claude Code + Codex AGENTS.md + Both); live-progress install UI.
-- **v5.2** — polish-loop reliability. `--reduced-motion` capture flag, `--routes URL1,URL2` multi-route mode, first supervised end-to-end run.
-- **v5.3** — Matt Pocock gaps closed. `/qualia-prd` (synthesize conversation → durable PRD), `/qualia-hook-gen` (CLAUDE.md instruction → deterministic Claude Code hook), `/qualia-optimize --deepen` Step 5b parallel-interface design (3 fan-out agents producing radically different interfaces).
+**The v5 line:**
+- **v5.0**, alignment discipline. CONTEXT.md domain glossary, decisions/ ADRs, `/qualia-zoom`, `/qualia-issues`, `/qualia-triage`, slim CLAUDE.md per Matt Pocock's instruction-budget rule, insights-driven hooks.
+- **v5.1**, autonomous visual-polish loop. Screenshots a URL at three viewports, scores 8 design dimensions with vision, fixes top issues, loops until pass or kill-switch. Multi-target installer (Claude Code + Codex AGENTS.md + Both).
+- **v5.2**, polish-loop reliability. `--reduced-motion` capture flag, `--routes URL1,URL2` multi-route mode, first supervised end-to-end run.
+- **v5.3**, Matt Pocock gaps closed. `/qualia-hook-gen` (CLAUDE.md instruction to deterministic Claude Code hook), `/qualia-optimize --deepen` Step 5b parallel-interface design (3 fan-out agents producing radically different interfaces).
+- **v5.4-5.5**, token-discipline and plan-discipline. Cache-aware spawn ordering, scope-reduction prohibition, decision-coverage audit, requirement-coverage check.
+- **v5.6**, Demo vs Full Project gate at kickoff. Mandatory discovery interview via `/qualia-discuss` in PROJECT MODE (8 questions for demos, 14 for full projects). Demo-extension branch in `/qualia-milestone` for client-signs-after-demo conversion.
+- **v5.7**, `/qualia-feature` consolidates `/qualia-quick` + `/qualia-task` into one auto-scoped command.
+- **v5.8**, surface cleanup. `/qualia-polish --loop` replaces `/qualia-polish-loop`. `/qualia-quick`, `/qualia-task`, and `/qualia-prd` removed (deprecated in v5.7).
 
 The Full Journey architecture carries forward: `/qualia-new` maps the entire project arc from kickoff to client handoff upfront, and the Road chains end-to-end in `--auto` mode with only two human gates per project.
 
@@ -40,6 +44,8 @@ npx qualia-framework@latest traces     # View recent hook telemetry
 
 Open Claude Code in any project directory.
 
+> **New to Qualia?** Open [`docs/onboarding.html`](docs/onboarding.html) in a browser for a one-page roadmap of the golden path. Best file to send a new hire.
+
 ### The Road — guided mode (default)
 
 ```
@@ -89,15 +95,13 @@ Two human gates per project. One halt case (gap-cycle limit exceeded on a failin
 /qualia-debug         # Structured debugging
 /qualia-review        # Production audit (scored diagnostics)
 /qualia-optimize      # Deep optimization pass (parallel specialist agents, --deepen mode with parallel-interface design)
-/qualia-quick         # Fast path for trivial fixes (skips planning)
-/qualia-task          # Build one thing properly (fresh builder, atomic commit, no phase plan)
+/qualia-feature       # Auto-scoped single-feature build (inline for trivia, fresh spawn for 1-5 files)
 /qualia-test          # Generate or run tests (--tdd mode for test-first workflow)
 /qualia-zoom          # Focus on a single file or function with full context
 /qualia-issues        # Break a phase plan into vertical-slice GitHub issues
 /qualia-triage        # Triage open issues through the ready-for-agent state machine
 /qualia-road          # View and navigate the project road (journey/milestone/phase status)
-/qualia-polish-loop   # Autonomous visual-polish loop: screenshot → vision-eval → fix → repeat (v5.1+)
-/qualia-prd           # Synthesize current conversation into a durable feature spec (v5.3+)
+/qualia-polish --loop # Autonomous visual-polish loop: screenshot, vision-eval, fix, repeat
 /qualia-hook-gen      # Convert a CLAUDE.md/rules instruction into a deterministic hook (v5.3+)
 ```
 
@@ -139,9 +143,9 @@ Project
 
 **Why it matters:** non-technical team members can follow the ladder from any entry point. `/qualia` and `/qualia-milestone` render JOURNEY.md as a visual ladder with current position highlighted. In the ERP, the primary operational dates are project deadline, milestone deadline, and employee shift submission date; framework tasks stay internal to agent execution.
 
-## What's Inside (v5.3.0)
+## What's Inside (v5.8.0)
 
-- **35 skills** — full Road (new / plan / build / verify / milestone / polish / ship / handoff / report), depth (discuss, research, map), navigation (qualia router, idk, pause, resume, road, help), quality (debug, review, optimize with `--deepen` parallel-interface design, quick, task, test, zoom, issues, triage), v5 flagships (`qualia-polish-loop`, `qualia-prd`, `qualia-hook-gen`), and meta (learn, skill-new, flush, postmortem)
+- **32 skills**, full Road (new / plan / build / verify / milestone / polish / ship / handoff / report), depth (discuss, research, map), navigation (qualia router, idk, pause, resume, road, help), quality (debug, review, optimize with `--deepen` parallel-interface design, feature, test, zoom, issues, triage), v5 flagships (`qualia-polish --loop`, `qualia-hook-gen`), and meta (learn, skill-new, flush, postmortem)
 - **9 agents** (each runs in fresh context): planner, builder, verifier, qa-browser, researcher, research-synthesizer, roadmapper, plan-checker, visual-evaluator
 - **12 hooks** (pure Node.js, cross-platform): session-start, auto-update, git-guardrails, branch-guard, pre-push tracking sync, migration-guard, pre-deploy-gate, pre-compact state save, stop-session-log, vercel-account-guard, env-empty-guard, supabase-destructive-guard
 - **6 always-loaded rules** (`rules/`): grounding, security, infrastructure, deployment, speed (CLI-first / MCP tier-list), architecture (deep modules / scout-for-shallow-code)

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/research-synthesizer.md

@@ -33,6 +33,7 @@ You receive:
 - `.planning/research/ARCHITECTURE.md`
 - `.planning/research/PITFALLS.md`
 - Project context (PROJECT.md summary)
+- `<scope>` — optional: `quick` for demo projects, `standard` (default) for full projects
 
 ## Output
 
@@ -72,7 +73,9 @@ Based on:
 - ARCHITECTURE.md build order → what depends on what, which foundation must land in Milestone 1 to support final-milestone requirements
 - PITFALLS.md → which risks stall later milestones and need to be addressed in Milestone 1 foundations
 
-Suggest a **2-5 milestone arc ending in Handoff**:
+**Quick scope (`<scope>quick</scope>`, demo projects):** Suggest a **single milestone** (no Handoff, no multi-milestone arc). The milestone is the demo itself — 2 to 4 phases that ship a real working surface end-to-end. Skip the "Handoff implications" section. The demo extends into a full project later via `/qualia-milestone` if the client signs; that conversion is handled there, not here.
+
+**Standard scope (default):** Suggest a **2-5 milestone arc ending in Handoff**:
 
 - **Milestone 1 · Foundation** — almost always. DB, auth, base layout, deploy pipeline.
 - **Milestone 2-{N-1} · Core + Expansion** — the value-delivering capabilities, ordered by dependency.

package/agents/researcher.md

@@ -25,11 +25,16 @@ You receive from the orchestrator:
 - `<domain>` — the project domain (e.g., "legal case management", "dental clinic booking", "voice agent for restaurants")
 - `<project_context>` — summary of PROJECT.md (core value, constraints, what they're building)
 - `<milestone_context>` — greenfield or subsequent
+- `<scope>` — optional: `quick` for demo projects, `standard` (default) for full projects
 - `<output_path>` — absolute path where you write your research file
 
 ## Tool Budget
 
-Maximum 8 external calls total per invocation: 3 Context7 queries + 3 WebFetch calls + 2 WebSearch queries. If you exhaust this budget, write what you have and mark remaining sections as `confidence: LOW`. Research is time-boxed, not exhaustive — a 10-minute deep dive with concrete sources beats a 30-minute wander.
+**Standard scope (default):** Maximum 8 external calls total per invocation — 3 Context7 queries + 3 WebFetch calls + 2 WebSearch queries.
+
+**Quick scope (`<scope>quick</scope>`, used by demo projects):** Maximum 3 external calls total — 1 Context7 query + 1 WebFetch + 1 WebSearch. The demo only needs enough research to validate the stack and surface the top pitfall — depth is wasted when there's a single milestone to ship. Drain local sources first (Steps 0a + 0b below); if local sources cover the dimension, skip external calls entirely.
+
+If you exhaust the budget, write what you have and mark remaining sections as `confidence: LOW`. Research is time-boxed, not exhaustive — a 10-minute deep dive with concrete sources beats a 30-minute wander.
 
 **Local-first.** Before any external call, exhaust local sources (Steps 0a + 0b in *How to Research* below). Most domains have already been researched and the answers live in NotebookLM notebooks or `~/qualia-memory`. Hitting the web for content we already have is silent token waste — and the local source is usually higher-quality (curated synthesis vs raw search results).
 

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/agents/visual-evaluator.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-visual-evaluator
-description: Vision-anchored evaluator for /qualia-polish-loop. Reads screenshots, scores 8 design dimensions against the rubric with cited evidence, returns top 3 issues + severity. Default: 3 (acceptable). Only deviates with quoted evidence.
+description: Vision-anchored evaluator for /qualia-polish --loop. Reads screenshots, scores 8 design dimensions against the rubric with cited evidence, returns top 3 issues + severity. Default: 3 (acceptable). Only deviates with quoted evidence.
 tools: Read, Grep, Glob
 ---
 

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

@@ -390,10 +390,10 @@ async function main() {
       if (fs.existsSync(refSrc)) {
         copy(refSrc, path.join(CLAUDE_DIR, "skills", skill, "REFERENCE.md"));
       }
-      // v5.1: Copy scripts/ subfolder if present (e.g. qualia-polish-loop ships
-      // playwright-capture.mjs, loop.mjs, score.mjs that the skill invokes at
-      // runtime). Recursive — preserves nested files. fixtures/ also copied
-      // for self-test scenarios.
+      // v5.1: Copy scripts/ subfolder if present (e.g. qualia-polish ships
+      // playwright-capture.mjs, loop.mjs, score.mjs that the --loop mode
+      // invokes at runtime). Recursive, preserves nested files. fixtures/
+      // also copied for self-test scenarios.
       for (const sub of ["scripts", "fixtures"]) {
         const subSrc = path.join(skillsDir, skill, sub);
         if (fs.existsSync(subSrc) && fs.statSync(subSrc).isDirectory()) {
@@ -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}`);
   }
@@ -893,7 +899,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     excludeDefault: true,
     tips: [
       "⬢ Lost? Type /qualia for the next step",
-      "⬢ Small fix? Use /qualia-quick to skip planning",
+      "⬢ Single feature? Use /qualia-feature, it auto-scopes",
       "⬢ End of day? /qualia-report submits your shift before clock-out",
       "⬢ Context isolation: every task gets a fresh AI brain",
       "⬢ The verifier doesn't trust claims — it greps the code",
@@ -1104,7 +1110,7 @@ function printSummary({ member, target, claudeInstalled }) {
   }
   console.log("");
   console.log(`  ${DIM}New project?${RESET}    ${TEAL}/qualia-new${RESET}`);
-  console.log(`  ${DIM}Quick fix?${RESET}      ${TEAL}/qualia-quick${RESET}`);
+  console.log(`  ${DIM}Single feature?${RESET} ${TEAL}/qualia-feature${RESET}`);
   console.log(`  ${DIM}End of day?${RESET}     ${TEAL}/qualia-report${RESET} ${DIM}(shift submission)${RESET}`);
   console.log(`  ${DIM}Stuck?${RESET}          ${TEAL}/qualia${RESET}`);
   console.log("");

package/bin/slop-detect.mjs

@@ -187,7 +187,7 @@ const SKIP_DIRS = new Set([
   "coverage", ".cache", "out", ".vercel", ".vscode", ".idea",
   ".planning", ".qa-screenshots",
   // v5.1: skip test fixtures by convention. Fixtures used as regression
-  // targets (e.g. /qualia-polish-loop's broken.html) intentionally violate
+  // targets (e.g. /qualia-polish --loop's broken.html) intentionally violate
   // the rules slop-detect enforces; scanning them flags real fixture bugs
   // as production slop.
   "fixtures", "__fixtures__",

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];