qualia-framework 6.2.9 → 6.3.0

package/docs/onboarding.html

@@ -496,9 +496,9 @@
       <div class="kit-group">
         <h4>Diagnose &amp; fix</h4>
         <dl>
-          <dt>/qualia-debug</dt><dd>Investigative debugging. Finds root cause, applies a minimal fix, writes a debug report.</dd>
-          <dt>/qualia-review</dt><dd>Production audit with severity-scored findings. Run before a big deploy.</dd>
-          <dt>/qualia-optimize</dt><dd>Deep pass for performance, design, architecture. Spawns parallel specialists.</dd>
+          <dt>/qualia-fix</dt><dd>Repair lane. Finds root cause, applies a minimal fix, verifies it, writes a fix report.</dd>
+          <dt>/qualia-review</dt><dd>Read-only production audit with severity-scored findings. Run before a big deploy.</dd>
+          <dt>/qualia-optimize</dt><dd>Deep improvement map for performance, design, alignment, and architecture. Spawns parallel specialists.</dd>
           <dt>/qualia-postmortem</dt><dd>Self-healing layer. After a failed verify, identifies which agent or rule should have caught it and proposes a delta.</dd>
         </dl>
       </div>
@@ -521,18 +521,14 @@
       <div class="kit-group">
         <h4>Build something small</h4>
         <dl>
-          <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>
+          <dt>/qualia-feature</dt><dd>Auto-scoped: inline for trivia (copy, config tweak), fresh builder spawn for 1-5 file features. Broken existing behavior routes to /qualia-fix.</dd>
         </dl>
       </div>
       <div class="kit-group">
         <h4>Navigate the session</h4>
         <dl>
           <dt>/qualia</dt><dd>State router. Tells you the exact next command.</dd>
-          <dt>/qualia-idk</dt><dd>"Something feels off." Diagnoses confusion across .planning + codebase.</dd>
-          <dt>/qualia-pause</dt><dd>Save context for handoff to a future session.</dd>
-          <dt>/qualia-resume</dt><dd>Restore context and routing from a paused session.</dd>
           <dt>/qualia-road</dt><dd>Terminal map of the workflow. Headless-friendly.</dd>
-          <dt>/qualia-help</dt><dd>Open this kind of reference in the browser.</dd>
         </dl>
       </div>
     </div>
@@ -558,7 +554,6 @@
         <h4>Code archaeology</h4>
         <dl>
           <dt>/qualia-map</dt><dd>Brownfield onboarding. Map an existing codebase before adding to it.</dd>
-          <dt>/qualia-zoom</dt><dd>Map a small, unfamiliar code area in domain-glossary terms.</dd>
         </dl>
       </div>
     </div>
@@ -573,21 +568,16 @@
         <h4>Knowledge</h4>
         <dl>
           <dt>/qualia-learn</dt><dd>Save a learning, pattern, fix, or client preference. Persists across projects and sessions.</dd>
-          <dt>/qualia-flush</dt><dd>Promote daily-log raw entries to the curated knowledge tier.</dd>
         </dl>
       </div>
       <div class="kit-group">
         <h4>Issue queue</h4>
         <dl>
-          <dt>/qualia-issues</dt><dd>Break a phase plan into independent vertical-slice GitHub issues.</dd>
-          <dt>/qualia-triage</dt><dd>Route open issues into needs-info, ready-for-agent, ready-for-human.</dd>
         </dl>
       </div>
       <div class="kit-group">
         <h4>Extend the framework</h4>
         <dl>
-          <dt>/qualia-skill-new</dt><dd>Author a new Qualia skill or agent.</dd>
-          <dt>/qualia-hook-gen</dt><dd>Convert an instruction into a deterministic Claude Code hook.</dd>
         </dl>
       </div>
       <div class="kit-group">

package/guide.md

@@ -1,9 +1,11 @@
-# Qualia Developer Guide (v6.2.7)
+# Qualia Developer Guide (v6.3.0)
 
 > Follow the road. Type the commands. The framework handles the rest.
 > `--auto` chains the whole road end-to-end with only two human checkpoints per project.
 
-**v6.2.7 is the Codex runtime compatibility patch.** Codex installs now get native `~/.codex/hooks.json`, TOML agents, bin scripts, rules, skills, templates, knowledge, guide, and role config in addition to `AGENTS.md`.
+**v6.3.0 is the harness hardening patch.** The default command surface is 23 active skills, retired helper sources are removed and pruned from older installs, `/qualia-polish --vibe` absorbs the old vibe command, `qualia-framework eval --run --write` produces scored eval artifacts, and PASS transitions now require clean machine evidence when a phase contract exists.
+
+**v6.2.7 carries forward.** Codex installs now get native `~/.codex/hooks.json`, TOML agents, bin scripts, rules, skills, templates, knowledge, guide, and role config in addition to `AGENTS.md`.
 
 **v6.2.5 carries forward.** `qualia-framework project-snapshot --write` creates a single `.planning/snapshots/project-snapshot-*.json` artifact with project identifiers, current milestone/phase, closed milestones, lifetime counters, and a project progress percentage for explicit ERP/admin import.
 
@@ -13,9 +15,9 @@
 
 **v6.2.2 carries forward.** Framework builds, Memory remembers, ERP operates. ERP work packets can seed Claude/Codex sessions, `/qualia-report` can carry ERP-native IDs, and release verification now has a public `@latest` install smoke.
 
-**v6.2.1 carries forward.** Active docs match the v6.2 no-bot-commit model, the explicit `/qualia-report` ERP contract, the current 33-skill surface, and fail-closed `INSUFFICIENT EVIDENCE` behavior. `tests/refs.test.sh` guards those claims.
+**v6.2.1 carries forward.** Active docs match the v6.2 no-bot-commit model, the explicit `/qualia-report` ERP contract, the current skill surface, and fail-closed `INSUFFICIENT EVIDENCE` behavior. `tests/refs.test.sh` guards those claims.
 
-**v6.1.0 ships the design-pivot path you were missing.** New `/qualia-vibe` is fast aesthetic pivot (~3 min): swap design tokens, keep layout. Default proposes ONE direction per `rules/one-opinion.md` (the EventMaster discipline — never give the user a menu). Sub-modes: `--variants N` for the opt-in menu, `--extract URL` reverse-engineers DESIGN.md from a reference site, `--sync` shows code↔DESIGN.md drift and can patch DESIGN.md from code. Slop-detect grew banned fonts (Montserrat/Poppins/Lato/Open Sans) and a `--watch` flag for proactive single-file mode. Several design-surface bugs from v6.0 audit are fixed too (viewport mismatch, slop-detect path resolution in the polish loop, dead `/qualia-design` references, the bounce-easing token that contradicted design-laws).
+**v6.1.0 ships the design-pivot path you were missing.** New `/qualia-polish --vibe` is fast aesthetic pivot (~3 min): swap design tokens, keep layout. Default proposes ONE direction per `rules/one-opinion.md` (the EventMaster discipline — never give the user a menu). Sub-modes: `--variants N` for the opt-in menu, `--extract URL` reverse-engineers DESIGN.md from a reference site, `--sync` shows code↔DESIGN.md drift and can patch DESIGN.md from code. Slop-detect grew banned fonts (Montserrat/Poppins/Lato/Open Sans) and a `--watch` flag for proactive single-file mode. Several design-surface bugs from v6.0 audit are fixed too (viewport mismatch, slop-detect path resolution in the polish loop, dead `/qualia-design` references, the bounce-easing token that contradicted design-laws).
 
 **v6.2.0 removes hook-created bot commits.** `pre-push.js` stamps local `tracking.json` telemetry but no longer commits it. `pre-compact.js` is gone because `state.js` already gives stronger crash safety with atomic writes plus a journal. ERP sync remains explicit through `/qualia-report` POSTs, not passive git scraping.
 
@@ -25,7 +27,7 @@
 
 **v5.9.0 carries forward.** `tests/refs.test.sh` catches dead command references in user-facing surfaces on every release. `bin/erp-retry.js` is a real persistent retry queue for ERP report uploads. Four structured agents (verifier, plan-checker, roadmapper, qa-browser) run on Sonnet for ~40% per-phase cost cut, while builder/planner/researcher/visual-evaluator stay on Opus where the architectural and vision reasoning lives. The verifier downgrades to FAIL on any `INSUFFICIENT EVIDENCE` line.
 
-**Surface is 33 skills.** Use `/qualia-feature` for single-feature work and `/qualia-discuss` in PROJECT MODE for kickoff capture; `/qualia-polish --loop` for the autonomous visual loop; `/qualia-vibe` for fast layout-preserving aesthetic pivots.
+**Surface is 23 installed skills.** Use `/qualia-fix` for broken existing behavior, `/qualia-feature` for new single-feature work, and `/qualia-discuss` in PROJECT MODE for kickoff capture; `/qualia-polish --loop` for the autonomous visual loop; `/qualia-polish --vibe` for fast layout-preserving aesthetic pivots.
 
 ## The Road
 
@@ -81,20 +83,18 @@ Append `--auto` to `/qualia-new` and the framework chains every step:
 | Single feature | `/qualia-feature` | Auto-scoped: inline for trivia, fresh spawn for 1-5 files |
 | Finishing | `/qualia-polish` | Design and UX pass (scope-adaptive: component / route / app / redesign / critique / quick / loop) |
 | | `/qualia-polish --loop` | Autonomous visual-polish loop: screenshot, vision-eval, fix, repeat |
-| Pivot the vibe | `/qualia-vibe` | Fast aesthetic pivot (~3 min): swap tokens, keep layout. Propose ONE direction. |
-| | `/qualia-vibe --extract <URL>` | Reverse-engineer DESIGN.md from a reference site |
-| | `/qualia-vibe --sync` | Show / patch drift between code (CSS vars + Tailwind) and DESIGN.md |
+| Pivot the vibe | `/qualia-polish --vibe` | Fast aesthetic pivot (~3 min): swap tokens, keep layout. Propose ONE direction. |
+| | `/qualia-polish --vibe --extract <URL>` | Reverse-engineer DESIGN.md from a reference site |
+| | `/qualia-polish --vibe --sync` | Show / patch drift between code (CSS vars + Tailwind) and DESIGN.md |
 | | `/qualia-ship` | Deploy to production |
 | | `/qualia-handoff` | Deliver to client (4 mandatory deliverables) |
 | Reporting | `/qualia-report` | Log what you did (mandatory before clock-out) |
-| Zooming in | `/qualia-zoom` | Focus on a single file or function with full context |
-| Issues | `/qualia-issues` | Break a phase plan into vertical-slice GitHub issues |
-| Triage | `/qualia-triage` | Triage open issues through the ready-for-agent state machine |
 | Optimize | `/qualia-optimize --deepen` | Find shallow modules; v5.3+ spawns 3 parallel interface-design variants per candidate |
-| Hook gen | `/qualia-hook-gen` | Convert a CLAUDE.md/rules instruction into a deterministic hook (v5.3+) |
+| Harness eval | `qualia-framework eval --run --write` | Run machine contract checks and write scored eval artifacts for ERP/reporting |
+| Planning hygiene | `qualia-framework planning-hygiene scan` | Detect loose `.planning/` reports/assets before they turn into folder bloat |
 | Road view | `/qualia-road` | View and navigate journey/milestone/phase status |
 | Lost? | `/qualia` | Mechanical next-command router |
-| Confused? | `/qualia-idk` | Diagnostic — scans planning + code, explains what's going on |
+| Confused? | `/qualia` | Diagnostic — scans planning + code, explains what's going on |
 
 ## Full Journey Hierarchy
 
@@ -119,13 +119,13 @@ Hard rules (enforced by `state.js` and the roadmapper):
 3. **MVP first** — build what's asked, nothing extra
 4. **Every task has a `Why`** (story-file format) — if you can't explain why a task matters in one sentence, it probably shouldn't exist
 5. **`/qualia` is your friend** — lost? type it
-6. **`/qualia-idk` is your deeper friend** — not lost on "what command", but confused about the *situation*? Type `idk`.
+6. **`/qualia` is your deeper friend** — not lost on "what command", but confused about the *situation*? Type `idk`.
 
 ## When You're Stuck
 
 ```
 /qualia       ← "what command should I run next?" (state-driven, instant)
-/qualia-idk   ← "what's actually going on here?" (diagnostic, scans planning + code, ~30s)
+/qualia   ← "what's actually going on here?" (diagnostic, scans planning + code, ~30s)
 ```
 
 If neither helps, paste the error and ask Claude directly. If Claude can't fix it, tell Fawzi.
@@ -154,7 +154,7 @@ If neither helps, paste the error and ask Claude directly. If Claude can't fix i
 | Starting a quick throwaway | `/qualia-new --quick` |
 | Brownfield project | `/qualia-map` first, then `/qualia-new` |
 | Stuck picking next command | `/qualia` |
-| Confused about the situation | `/qualia-idk` |
+| Confused about the situation | `/qualia` |
 | Finished the last phase of a milestone | `/qualia-milestone` |
 | About to ship | `/qualia-ship` |
 | Client is ready to take over | `/qualia-handoff` |

package/hooks/fawzi-approval-guard.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// Silently records EMPLOYEE attempts to use "Fawzi said OK" style proxy
+// approval. This hook never blocks and never prints: the policy text teaches
+// the agent not to do it; this hook records when it still appears in tool input.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const crypto = require("crypto");
+
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(os.homedir(), ".claude");
+}
+
+const QUALIA_HOME = qualiaHome();
+const CONFIG = path.join(QUALIA_HOME, ".qualia-config.json");
+const EVENT_FILE = path.join(QUALIA_HOME, ".approval-policy-events.json");
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(file, data) {
+  try {
+    const dir = path.dirname(file);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${file}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+    try { fs.chmodSync(tmp, 0o600); } catch {}
+    fs.renameSync(tmp, file);
+  } catch {}
+}
+
+function collectStrings(value, out = []) {
+  if (typeof value === "string") out.push(value);
+  else if (Array.isArray(value)) value.forEach((v) => collectStrings(v, out));
+  else if (value && typeof value === "object") {
+    for (const v of Object.values(value)) collectStrings(v, out);
+  }
+  return out;
+}
+
+function hookInputText() {
+  try {
+    if (process.stdin.isTTY) return "";
+    const raw = fs.readFileSync(0, "utf8");
+    if (!raw) return "";
+    try {
+      const parsed = JSON.parse(raw);
+      return collectStrings(parsed.tool_input || parsed).join("\n");
+    } catch {
+      return raw;
+    }
+  } catch {
+    return "";
+  }
+}
+
+function approvalClaim(text) {
+  const normalized = String(text || "").replace(/\s+/g, " ").trim();
+  if (!normalized) return "";
+  const patterns = [
+    /\bfawzi\b.{0,80}\b(said|says|told|approved|approves|okayed|ok'd|allowed|allows|authorized|authorizes|confirmed)\b.{0,80}\b(ok|okay|fine|yes|ship|deploy|go ahead|do it|allowed|approved)?/i,
+    /\bfawzi\s+is\s+(here|with\s+me|beside\s+me)\b.{0,80}\b(ok|okay|fine|yes|approved|approves|allow|allows|ship|deploy|go ahead|do it)\b/i,
+    /\b(owner|boss)\b.{0,40}\b(said|says|approved|approves|okayed|ok'd)\b.{0,60}\b(ok|okay|fine|yes|ship|deploy|go ahead|do it)\b/i,
+  ];
+  for (const re of patterns) {
+    const m = normalized.match(re);
+    if (m) return m[0].slice(0, 220);
+  }
+  return "";
+}
+
+function recordLocal(config, sample) {
+  const data = readJson(EVENT_FILE, { counts: {}, events: [] });
+  if (!data.counts || typeof data.counts !== "object") data.counts = {};
+  if (!Array.isArray(data.events)) data.events = [];
+
+  const key = config.code || config.installed_by || "unknown";
+  const prev = data.counts[key] || {};
+  const count = (prev.total || 0) + 1;
+  const event = {
+    type: "proxy_owner_approval_claim",
+    actor_code: config.code || "",
+    actor_name: config.installed_by || "",
+    actor_role: config.role || "",
+    count,
+    sample,
+    project: path.basename(process.cwd()),
+    cwd: process.cwd(),
+    recorded_at: new Date().toISOString(),
+  };
+
+  data.counts[key] = {
+    actor_code: event.actor_code,
+    actor_name: event.actor_name,
+    actor_role: event.actor_role,
+    total: count,
+    last_seen_at: event.recorded_at,
+  };
+  data.events.push(event);
+  data.events = data.events.slice(-200);
+  writeJson(EVENT_FILE, data);
+  return event;
+}
+
+function enqueueErp(config, event) {
+  try {
+    const retryPath = path.join(QUALIA_HOME, "bin", "erp-retry.js");
+    if (!fs.existsSync(retryPath)) return;
+    if (config.erp && config.erp.enabled === false) return;
+    const erpUrl = (config.erp && config.erp.url) || "https://portal.qualiasolutions.net";
+    const { enqueue } = require(retryPath);
+    enqueue({
+      client_report_id: `QS-POLICY-${(event.actor_code || "UNKNOWN").replace(/[^A-Z0-9-]/gi, "")}-${event.count}`,
+      idempotency_key: crypto.randomUUID ? crypto.randomUUID() : "",
+      url: `${erpUrl.replace(/\/$/, "")}/api/v1/policy-events`,
+      payload: JSON.stringify(event),
+      last_error: "",
+    });
+  } catch {}
+}
+
+try {
+  const config = readJson(CONFIG, {});
+  if ((config.role || "").toUpperCase() === "OWNER") process.exit(0);
+  if ((config.role || "").toUpperCase() !== "EMPLOYEE") process.exit(0);
+
+  const sample = approvalClaim(hookInputText());
+  if (!sample) process.exit(0);
+
+  const event = recordLocal(config, sample);
+  enqueueErp(config, event);
+} catch {}
+
+process.exit(0);

package/hooks/pre-deploy-gate.js

@@ -21,6 +21,8 @@ function qualiaHome() {
 }
 
 const QUALIA_HOME = qualiaHome();
+const CONFIG = path.join(QUALIA_HOME, ".qualia-config.json");
+let HOOK_COMMAND = null;
 
 // Self-filter on the proposed bash command — only act when the user is
 // actually trying to deploy. Claude Code's `if: "Bash(vercel --prod*)"` does
@@ -44,7 +46,8 @@ const QUALIA_HOME = qualiaHome();
     }
   } catch {}
   if (command === null) return; // malformed or empty stdin — run full gate
-  if (!/^\s*(npx\s+)?vercel\s+(--prod|deploy\s+--prod)\b/.test(command)) {
+  HOOK_COMMAND = command;
+  if (!/^\s*(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(npx\s+)?vercel\s+(--prod|deploy\s+--prod)\b/.test(command)) {
     process.exit(0);
   }
 })();
@@ -107,6 +110,76 @@ function hasScript(name) {
   }
 }
 
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function readTrackingState() {
+  try {
+    const tracking = JSON.parse(fs.readFileSync(path.join(process.cwd(), ".planning", "tracking.json"), "utf8"));
+    return {
+      status: tracking.status || "",
+      verification: tracking.verification || "",
+      next_command: tracking.next_command || "",
+    };
+  } catch {
+    return null;
+  }
+}
+
+function readState() {
+  const stateJs = path.join(QUALIA_HOME, "bin", "state.js");
+  if (fs.existsSync(stateJs)) {
+    try {
+      const r = spawnSync(process.execPath, [stateJs, "check"], {
+        encoding: "utf8",
+        timeout: 3000,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      if (r.status === 0 && r.stdout) return JSON.parse(r.stdout);
+    } catch {}
+  }
+  return readTrackingState();
+}
+
+function blockDeploy(reason, nextCommand) {
+  console.error(`BLOCKED: ${reason}`);
+  if (nextCommand) console.error(`Run: ${nextCommand}`);
+  _trace("pre-deploy-gate", "block", { reason, next_command: nextCommand || "" });
+  process.exit(2);
+}
+
+function enforceShipPolicy() {
+  if (!HOOK_COMMAND) return;
+
+  const config = readConfig();
+  const role = String(config.role || "").toUpperCase();
+  const force = process.env.QUALIA_SHIP_FORCE === "1" || /\bQUALIA_SHIP_FORCE=1\b/.test(HOOK_COMMAND);
+  const state = readState();
+  const status = state && state.status ? String(state.status) : "";
+  const verification = state && state.verification ? String(state.verification) : "";
+  const nextCommand = (state && state.next_command) || "/qualia";
+
+  if (force && role !== "OWNER") {
+    blockDeploy("QUALIA_SHIP_FORCE is OWNER-only.", nextCommand);
+  }
+
+  // If this is not a Qualia-managed project, keep the legacy behavior: run the
+  // quality/security gates but do not invent state.
+  if (!state || !status) return;
+
+  const shippable = status === "polished" || (status === "verified" && verification === "pass");
+  if (!shippable && !force) {
+    blockDeploy(`Ship refused from state '${status}' (verification: ${verification || "none"}).`, nextCommand);
+  }
+}
+
+enforceShipPolicy();
+
 // Directories that should never be walked (build outputs, deps, caches).
 const EXCLUDED_DIRS = new Set([
   "node_modules",

package/hooks/session-start.js

@@ -25,6 +25,9 @@ function qualiaHome() {
   if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
   const parent = path.basename(path.dirname(__dirname));
   if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  if (fs.existsSync(path.join(path.dirname(__dirname), "bin", "qualia-ui.js"))) {
+    return path.dirname(__dirname);
+  }
   return path.join(HOME, ".claude");
 }
 
@@ -36,6 +39,7 @@ const NOTIF_FILE = path.join(QUALIA_HOME, ".qualia-update-available.json");
 const HEALTH_FILE = path.join(QUALIA_HOME, ".qualia-install-health.json");
 const ERP_RETRY = path.join(QUALIA_HOME, "bin", "erp-retry.js");
 const ERP_QUEUE = path.join(QUALIA_HOME, ".erp-retry-queue.json");
+const WORK_PACKET_BIN = path.join(QUALIA_HOME, "bin", "work-packet.js");
 
 // Critical files referenced by skills via @-import. If any are missing, skills
 // silently get empty context and produce ungrounded output. We spot-check these
@@ -97,6 +101,29 @@ function getNextCommand() {
   }
 }
 
+function readWorkPacket() {
+  try {
+    if (!fs.existsSync(WORK_PACKET_BIN)) return null;
+    const mod = require(WORK_PACKET_BIN);
+    if (!mod || typeof mod.readLocalWorkPacket !== "function") return null;
+    return mod.readLocalWorkPacket(process.cwd());
+  } catch {
+    return null;
+  }
+}
+
+function renderWorkPacketContext() {
+  const packet = readWorkPacket();
+  if (!packet) return;
+  const project = packet.project && packet.project.name ? packet.project.name : "ERP mission";
+  const deadline = packet.deadline_date || "no deadline";
+  const next = packet.next_command || "/qualia";
+  const employee = packet.employee && packet.employee.name ? ` · ${packet.employee.name}` : "";
+  const text = `${project}: due ${deadline} · next ${next}${employee}`;
+  if (fs.existsSync(UI)) runUi("info", text);
+  else console.log(`QUALIA: ${text}`);
+}
+
 function readConfig() {
   try {
     return JSON.parse(fs.readFileSync(path.join(QUALIA_HOME, ".qualia-config.json"), "utf8"));
@@ -178,6 +205,7 @@ try {
     fallbackText();
   } else if (fs.existsSync(STATE_FILE)) {
     runUi("banner", "router");
+    renderWorkPacketContext();
     const next = getNextCommand();
     if (next) {
       console.log("");
@@ -185,7 +213,7 @@ try {
     }
   } else if (fs.existsSync(CONTINUE_HERE)) {
     runUi("banner", "resume");
-    runUi("warn", "Previous session found — type /qualia-resume to pick up where you left off");
+    runUi("warn", "Previous session found — type /qualia to pick up where you left off");
     console.log("");
   } else {
     // No project — show a welcoming first-run experience

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "6.2.9",
+  "version": "6.3.0",
   "description": "Claude Code and Codex workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"

package/qualia-design/design-rubric.md

@@ -4,7 +4,7 @@ globs: ["*.tsx", "*.jsx", "*.css", "*.scss", "*.html", "*.vue", "*.svelte"]
 
 # Design Rubric
 
-Anchored 1-5 scoring across 8 dimensions. Used by the verifier agent to score frontend phases. Used by `/qualia-polish --critique` for read-only audits.
+Anchored 1-5 scoring across 9 dimensions. Used by the verifier agent to score frontend phases. Used by `/qualia-polish --critique` for read-only audits.
 
 ## How to score
 
@@ -25,9 +25,9 @@ If a vision model is critiquing screenshots, it must score against this rubric.
 
 Score only what is scope-relevant. A `/qualia-polish src/components/Button.tsx` review scores Typography, Color, States, Motion, Microcopy. Skip Layout Originality and Container Depth — they're component-internal concerns at most.
 
-A whole-app `/qualia-polish` scores all 8 dimensions across multiple representative routes.
+A whole-app `/qualia-polish` scores all 9 dimensions across multiple representative routes.
 
-## The 8 dimensions
+## The 9 dimensions
 
 ### 1. Typography
 
@@ -125,10 +125,22 @@ Evidence: grep for banned phrases, sample of empty/error states
 
 Evidence: max DOM nesting depth on cards/panels, grep for `border-left` decorative usage
 
+### 9. Visual system & graphics
+
+| Score | Criteria |
+|---|---|
+| 1 | Page is only generic cards/text where product, state, data, or brand object should be visible. Or visual is decorative noise unrelated to meaning. |
+| 2 | Simple icon/illustration exists but could fit any project. No product/domain specificity. |
+| 3 | Visual supports the page: screenshot, product image, simple diagram, chart, or meaningful icon system. |
+| 4 | Visual system is custom to the product/domain: annotated diagram, varied chart, bespoke hero composition, real media, or meaningful motion. |
+| 5 | Complex visual is memorable and useful: product-in-context scene, interactive graph/map/timeline, 3D/canvas/WebGL, or data visualization with clear insight and accessible fallback. |
+
+Evidence: visual type, file:line references, relationship to PRODUCT.md/CONTEXT.md, reduced-motion or static fallback
+
 ## Aggregate score
 
 ```
-total       = sum of dimension scores (max 40)
+total       = sum of dimension scores (max 45)
 average     = total / count_of_scored_dimensions
 phase_pass  = ALL scored dimensions ≥ 3
 phase_fail  = ANY scored dimension < 3
@@ -149,7 +161,7 @@ A phase fails if any dimension is below 3. Same gate as functional verification.
 | Layout originality | 2 | `app/page.tsx:42-78` is a three-column feature grid in section 2 — first-order slop. Rework. |
 | ... | ... | ... |
 
-**Aggregate:** 28/40 (avg 3.5)
+**Aggregate:** 32/45 (avg 3.56)
 **Phase verdict:** FAIL — Layout Originality at 2 blocks the phase.
 **Fix priority:** Rework section 2. Replace three-column grid with varied-height layout per `design-brand.md` §Layout.
 ```

package/qualia-design/frontend.md

@@ -109,10 +109,14 @@ These are Qualia brand standards — mandatory for every frontend component. Not
 If `.planning/DESIGN.md` exists in the project, it takes precedence over these defaults.
 Read it before any frontend work. It contains project-specific: palette, typography, spacing, component patterns.
 
+For redesigns and full-app polish, also read:
+- `qualia-design/design-reference.md` for motion, accessibility, responsive, and performance depth
+- `qualia-design/graphics.md` for complex graphics, charts, canvas, 3D, visual systems, and media rules
+
 ## Qualia design commands
 - `/qualia-polish` — design pass, scope-adaptive (component / section / app / redesign / critique / quick / loop)
-- `/qualia-vibe` — fast aesthetic pivot (swap tokens, keep layout) + reverse-engineer from URL + code↔DESIGN.md sync
+- `/qualia-polish --vibe` — fast aesthetic pivot (swap tokens, keep layout) + reverse-engineer from URL + code↔DESIGN.md sync
 - `/qualia-review` — scored production audit
 
 ### Recommended workflow
-1. Build feature → 2. `/qualia-polish` to polish within the current vibe → 3. `/qualia-vibe` when the vibe itself needs to change → 4. `/qualia-polish --loop` for autonomous visual QA → ship.
+1. Build feature → 2. `/qualia-polish` to polish within the current vibe → 3. `/qualia-polish --vibe` when the vibe itself needs to change → 4. `/qualia-polish --redesign` when the whole surface needs stronger visual concept/graphics → 5. `/qualia-polish --loop` for autonomous visual QA → ship.

package/qualia-design/graphics.md

@@ -0,0 +1,47 @@
+---
+globs: ["*.tsx", "*.jsx", "*.css", "*.scss", "*.html", "*.svg", "*.canvas", "*.webgl"]
+---
+
+# Complex Graphics & Visual Systems
+
+Loaded by `/qualia-polish --redesign`, `/qualia-polish --loop`, and any polish pass where the page needs stronger visual identity than typography and spacing alone can provide.
+
+## When To Add Complex Visuals
+
+Use richer graphics when they clarify the product, reveal state, or create a memorable first-viewport signal:
+
+- Product object, venue, person, or service that needs immediate recognition
+- Operational dashboard where relationships, flow, status, or hierarchy matter
+- Brand site whose current page is only text blocks and cards
+- Demo or portfolio page where the work itself should be visible
+- Game, spatial tool, voice/AI workflow, analytics surface, map, timeline, graph, or process flow
+
+Do not add complex visuals as decoration. A visual must either explain, orient, compare, or make the brand/product unforgettable.
+
+## Visual Types
+
+Pick the strongest type for the job:
+
+| Need | Prefer |
+|---|---|
+| Show real product/place/person | Photo, screenshot, generated bitmap, or image search asset |
+| Show relationships | Node graph, map, flow field, timeline, Sankey, chord, matrix |
+| Show data | Custom chart with annotations, small multiples, sparklines, heatmap |
+| Show process | Step path, layered diagram, animated system map |
+| Create brand memory | Bespoke hero composition, editorial collage, product-in-context scene |
+| Need depth/spatiality | Three.js full-bleed scene, CSS 3D, canvas/WebGL |
+| Need icons | One icon family, ideally lucide if available |
+
+## Quality Rules
+
+1. Use real or generated bitmap imagery when the user needs to inspect a real thing. Do not substitute abstract SVG blobs.
+2. For 3D, use Three.js and verify the canvas is nonblank at desktop and mobile viewports.
+3. For charts, annotate the insight. A chart without labels or a takeaway is decoration.
+4. For diagrams, keep text short and legible at 375px width.
+5. For generated assets, save them under project assets, not `.planning/`.
+6. For motion, connect animation to meaning: reveal sequence, state change, data transition, or spatial relationship.
+7. Respect reduced motion. Complex visuals must have a static fallback.
+
+## Redesign Expectation
+
+`/qualia-polish --redesign` must consider at least one complex-visual concept for the first viewport. It may reject the concept only if it explains why typography/layout alone is stronger for that product.

package/rules/codex-goal.md

@@ -39,7 +39,7 @@ If the answer is `claude`, **skip this entire rule** — Claude Code has no equi
 
 - The user is on Claude Code (no `/goal` surface).
 - A goal is already active for this thread (Codex rejects `update_goal` when one exists — call `thread/goal/get` first if you're using the tool API directly).
-- The work is open-ended exploration with no clear objective (e.g. `/qualia-idk`, `/qualia-discuss`). Goals are for executing a defined scope.
+- The work is open-ended exploration with no clear objective (e.g. `/qualia`, `/qualia-discuss`). Goals are for executing a defined scope.
 
 ## Why
 

package/rules/command-output.md

@@ -0,0 +1,35 @@
+---
+alwaysApply: true
+---
+
+# Command Output Contract
+
+Every Qualia command must be transparent before, during, and after work. Users should never wonder what the command is doing, what it can change, or what the next step is.
+
+## Required Shape
+
+Every command should expose these seven lines or their equivalent:
+
+```text
+Command: /qualia-{name} {mode}
+Scope: {files/routes/project area}
+Intent: {audit|investigate|repair|build|polish|ship|report}
+Mutation: none | planned | active | blocked
+Evidence: {files read, commands run, sources checked}
+Output: {files/reports/commits produced}
+Next: {next command or done}
+```
+
+## Rules
+
+1. Start with a `qualia-ui.js banner` whenever the command has an existing banner mode.
+2. State whether the command is read-only or mutating before editing.
+3. For mutating commands, name the exact files or route family before writing.
+4. For audit or investigation commands, name the evidence commands and report path.
+5. For design commands, name the design substrate loaded from `qualia-design/` and `.planning/DESIGN.md`.
+6. End with a `qualia-ui.js end` next command. If there is no next command, say `done`.
+7. If the command blocks, say why and route to the smallest useful next command.
+
+## Anti-Pattern
+
+Do not answer with only a prose paragraph like "Done, I fixed it." The command must tell the user what happened and where the evidence lives.

package/rules/one-opinion.md

@@ -1,6 +1,6 @@
 # One Opinion (design-decision discipline)
 
-Loaded on demand by design-adjacent skills: `/qualia-vibe`, `/qualia-polish`, `/qualia-new` (DESIGN.md creation step), `/qualia-discuss` PROJECT MODE. Not always-on — most skills don't need it.
+Loaded on demand by design-adjacent skills: `/qualia-polish --vibe`, `/qualia-polish`, `/qualia-new` (DESIGN.md creation step), `/qualia-discuss` PROJECT MODE. Not always-on — most skills don't need it.
 
 ## The rule
 
@@ -34,7 +34,7 @@ Owners and clients have a strong sense of what they DON'T want and a weaker sens
 - The user explicitly asked for options ("show me 3 directions", "give me a menu").
 - The decision is technical, not aesthetic (e.g. "use Postgres or MongoDB?" — those have objectively different tradeoffs and should be discussed, not opinionated).
 - A locked decision in `.planning/decisions/*.md` already exists — surface it, don't re-decide.
-- The framework command explicitly supports a `--variants` mode (e.g. `/qualia-vibe --variants 3`), which is the user opting into the menu surface.
+- The framework command explicitly supports a `--variants` mode (e.g. `/qualia-polish --vibe --variants 3`), which is the user opting into the menu surface.
 
 ## Output shape