qualia-framework 6.2.9 → 6.2.10

package/bin/trust-score.js

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+// Qualia trust score — compact harness health summary.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const pc = require("./plan-contract.js");
+const ledger = require("./state-ledger.js");
+const { binFiles } = require("./runtime-manifest.js");
+
+const HOMES = [
+  { name: "Claude", dir: path.join(os.homedir(), ".claude") },
+  { name: "Codex", dir: path.join(os.homedir(), ".codex") },
+];
+
+const REQUIRED_BIN = binFiles();
+
+const REQUIRED_HOOKS = [
+  "session-start.js", "auto-update.js", "branch-guard.js", "pre-push.js",
+  "pre-deploy-gate.js", "migration-guard.js", "git-guardrails.js",
+  "stop-session-log.js", "vercel-account-guard.js", "env-empty-guard.js",
+  "supabase-destructive-guard.js",
+];
+
+const REQUIRED_DESIGN_FILES = [
+  "design-laws.md",
+  "design-rubric.md",
+  "design-brand.md",
+  "design-product.md",
+  "design-reference.md",
+  "frontend.md",
+  "graphics.md",
+];
+
+const REQUIRED_EMPLOYEE_SKILLS = [
+  "qualia-doctor",
+  "qualia-road",
+  "qualia-resume",
+  "qualia-pause",
+  "qualia-report",
+];
+
+function exists(p) {
+  try { return fs.existsSync(p); } catch { return false; }
+}
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
+}
+function readText(p) {
+  try { return fs.readFileSync(p, "utf8"); } catch { return ""; }
+}
+
+function installedHomes() {
+  return HOMES.filter((h) => exists(path.join(h.dir, ".qualia-config.json")));
+}
+
+function inspectInstall(homes) {
+  if (homes.length === 0) {
+    return { status: "fail", score: 0, issues: ["no Qualia install config found"], targets: [] };
+  }
+  const issues = [];
+  for (const home of homes) {
+    for (const f of REQUIRED_BIN) {
+      if (!exists(path.join(home.dir, "bin", f))) issues.push(`${home.name}: missing bin/${f}`);
+    }
+    if (home.name === "Claude") {
+      if (!exists(path.join(home.dir, "CLAUDE.md"))) issues.push("Claude: missing CLAUDE.md");
+      if (!exists(path.join(home.dir, "settings.json"))) issues.push("Claude: missing settings.json");
+    } else {
+      if (!exists(path.join(home.dir, "AGENTS.md"))) issues.push("Codex: missing AGENTS.md");
+      if (!exists(path.join(home.dir, "hooks.json"))) issues.push("Codex: missing hooks.json");
+      if (!exists(path.join(home.dir, "config.toml"))) issues.push("Codex: missing config.toml");
+    }
+  }
+  return {
+    status: issues.length ? "degraded" : "pass",
+    score: issues.length ? Math.max(6, 20 - issues.length * 2) : 20,
+    issues,
+    targets: homes.map((h) => h.name),
+  };
+}
+
+function inspectHooks(homes) {
+  if (homes.length === 0) return { status: "fail", score: 0, issues: ["no install targets"] };
+  const issues = [];
+  for (const home of homes) {
+    for (const h of REQUIRED_HOOKS) {
+      if (!exists(path.join(home.dir, "hooks", h))) issues.push(`${home.name}: missing hooks/${h}`);
+    }
+  }
+  return {
+    status: issues.length ? "degraded" : "pass",
+    score: issues.length ? Math.max(4, 12 - issues.length) : 12,
+    issues,
+  };
+}
+
+function inspectProject(cwd) {
+  const planning = path.join(cwd, ".planning");
+  if (!exists(planning)) return { status: "not_applicable", score: 12, issues: [], phase: null };
+  const tracking = readJson(path.join(planning, "tracking.json"));
+  const stateText = readText(path.join(planning, "STATE.md"));
+  const issues = [];
+  if (!tracking) issues.push("tracking.json missing or invalid");
+  if (!stateText) issues.push("STATE.md missing");
+  const phaseMatch = stateText.match(/^Phase:\s*(\d+)/m);
+  const statusMatch = stateText.match(/^Status:\s*(.+)$/m);
+  const phase = phaseMatch ? Number(phaseMatch[1]) : (tracking && Number(tracking.phase)) || 1;
+  if (!phaseMatch && stateText) issues.push("STATE.md phase header missing");
+  if (!statusMatch && stateText) issues.push("STATE.md status missing");
+  return {
+    status: issues.length ? "degraded" : "pass",
+    score: issues.length ? Math.max(4, 12 - issues.length * 4) : 12,
+    issues,
+    phase,
+    project_status: statusMatch ? statusMatch[1].trim() : tracking?.status || "",
+  };
+}
+
+function inspectContracts(cwd, phase) {
+  const planning = path.join(cwd, ".planning");
+  if (!exists(planning) || !phase) return { status: "not_applicable", score: 18, issues: [] };
+  const planPath = path.join(planning, `phase-${phase}-plan.md`);
+  const contractPath = path.join(planning, `phase-${phase}-contract.json`);
+  if (!exists(planPath)) return { status: "not_applicable", score: 18, issues: [] };
+  if (!exists(contractPath)) return { status: "degraded", score: 6, issues: [`phase ${phase}: JSON contract missing`] };
+  const loaded = pc.readContractFile(contractPath);
+  if (!loaded.ok) return { status: "fail", score: 0, issues: [`phase ${phase}: contract unreadable (${loaded.message || loaded.error})`] };
+  const errors = pc.validate(loaded.contract);
+  if (errors.length) return { status: "fail", score: 0, issues: [`phase ${phase}: contract invalid (${errors.length} issue(s))`] };
+  const drift = pc.checkDrift(contractPath, planPath);
+  if (drift.ok && drift.drift) return { status: "fail", score: 0, issues: [`phase ${phase}: contract drifted from plan`] };
+  return { status: "pass", score: 18, issues: [], contract: path.relative(cwd, contractPath) };
+}
+
+function inspectLedger(cwd) {
+  const planning = path.join(cwd, ".planning");
+  if (!exists(planning)) return { status: "not_applicable", score: 10, issues: [] };
+  const file = ledger.ledgerPath(cwd);
+  if (!exists(file)) return { status: "degraded", score: 4, issues: ["state ledger missing"] };
+  const result = ledger.validate(cwd);
+  if (!result.ok) return { status: "fail", score: 0, issues: result.errors };
+  if (result.count === 0) return { status: "degraded", score: 4, issues: ["state ledger empty"] };
+  return { status: "pass", score: 10, issues: [], events: result.count };
+}
+
+function inspectMemory(homes) {
+  if (homes.length === 0) return { status: "fail", score: 0, issues: ["no install targets"] };
+  const issues = [];
+  for (const home of homes) {
+    if (!exists(path.join(home.dir, "knowledge", "index.md"))) issues.push(`${home.name}: missing knowledge/index.md`);
+    if (!exists(path.join(home.dir, "knowledge", "agents.md"))) issues.push(`${home.name}: missing knowledge/agents.md`);
+    if (!exists(path.join(home.dir, "knowledge", "daily-log"))) issues.push(`${home.name}: missing knowledge/daily-log`);
+  }
+  return {
+    status: issues.length ? "degraded" : "pass",
+    score: issues.length ? Math.max(2, 5 - issues.length) : 5,
+    issues,
+  };
+}
+
+function inspectDesign(homes) {
+  if (homes.length === 0) return { status: "fail", score: 0, issues: ["no install targets"] };
+  const issues = [];
+  for (const home of homes) {
+    for (const f of REQUIRED_DESIGN_FILES) {
+      if (!exists(path.join(home.dir, "qualia-design", f))) issues.push(`${home.name}: missing qualia-design/${f}`);
+    }
+    if (!exists(path.join(home.dir, "skills", "qualia-polish", "SKILL.md"))) {
+      issues.push(`${home.name}: missing qualia-polish skill`);
+    }
+    if (!exists(path.join(home.dir, "skills", "qualia-vibe", "SKILL.md"))) {
+      issues.push(`${home.name}: missing qualia-vibe skill`);
+    }
+    if (!exists(path.join(home.dir, "agents", home.name === "Codex" ? "visual-evaluator.toml" : "visual-evaluator.md"))) {
+      issues.push(`${home.name}: missing visual-evaluator agent`);
+    }
+    if (!exists(path.join(home.dir, "bin", "slop-detect.mjs"))) {
+      issues.push(`${home.name}: missing slop-detect.mjs`);
+    }
+  }
+  return {
+    status: issues.length ? "degraded" : "pass",
+    score: issues.length ? Math.max(2, 8 - issues.length) : 8,
+    issues,
+  };
+}
+
+function inspectEmployeeExperience(homes) {
+  if (homes.length === 0) return { status: "fail", score: 0, issues: ["no install targets"] };
+  const issues = [];
+  for (const home of homes) {
+    for (const skill of REQUIRED_EMPLOYEE_SKILLS) {
+      if (!exists(path.join(home.dir, "skills", skill, "SKILL.md"))) issues.push(`${home.name}: missing ${skill} skill`);
+    }
+    if (!exists(path.join(home.dir, "qualia-guide.md"))) issues.push(`${home.name}: missing qualia-guide.md`);
+    if (!exists(path.join(home.dir, "qualia-templates", "help.html"))) issues.push(`${home.name}: missing help.html`);
+  }
+  return {
+    status: issues.length ? "degraded" : "pass",
+    score: issues.length ? Math.max(1, 5 - issues.length) : 5,
+    issues,
+  };
+}
+
+function inspectErp(homes) {
+  if (homes.length === 0) return { status: "not_applicable", score: 10, issues: [] };
+  const issues = [];
+  let enabled = false;
+  let queueCount = 0;
+  for (const home of homes) {
+    const cfg = readJson(path.join(home.dir, ".qualia-config.json")) || {};
+    if (cfg.erp && cfg.erp.enabled !== false) {
+      enabled = true;
+      const keyFile = path.join(home.dir, cfg.erp.api_key_file || ".erp-api-key");
+      if (!exists(keyFile)) issues.push(`${home.name}: ERP enabled but API key missing`);
+    }
+    const queue = readJson(path.join(home.dir, ".erp-retry-queue.json"));
+    if (Array.isArray(queue)) queueCount += queue.length;
+  }
+  if (!enabled) return { status: "not_applicable", score: 10, issues: [], queue_count: queueCount };
+  if (queueCount > 0) issues.push(`ERP retry queue has ${queueCount} item(s)`);
+  return {
+    status: issues.length ? "degraded" : "pass",
+    score: issues.length ? Math.max(3, 10 - issues.length * 3) : 10,
+    issues,
+    queue_count: queueCount,
+  };
+}
+
+function buildTrustScore(cwd = process.cwd()) {
+  const homes = installedHomes();
+  const install = inspectInstall(homes);
+  const hooks = inspectHooks(homes);
+  const project = inspectProject(cwd);
+  const contracts = inspectContracts(cwd, project.phase);
+  const state_ledger = inspectLedger(cwd);
+  const memory = inspectMemory(homes);
+  const erp = inspectErp(homes);
+  const design = inspectDesign(homes);
+  const employee_experience = inspectEmployeeExperience(homes);
+  const checks = { install, hooks, project, contracts, state_ledger, memory, erp, design, employee_experience };
+  const score = Math.max(0, Math.min(100, Object.values(checks).reduce((n, c) => n + (c.score || 0), 0)));
+  const failCount = Object.values(checks).filter((c) => c.status === "fail").length;
+  const degradedCount = Object.values(checks).filter((c) => c.status === "degraded").length;
+  const status = failCount ? "FAIL" : degradedCount ? "DEGRADED" : "PASS";
+  return { ok: failCount === 0, status, score, generated_at: new Date().toISOString(), checks };
+}
+
+function printHuman(result) {
+  console.log(`Trust score: ${result.score}/100 (${result.status})`);
+  for (const [name, check] of Object.entries(result.checks)) {
+    const label = `${name[0].toUpperCase()}${name.slice(1)}`;
+    console.log(`${label}: ${check.status} (${check.score})`);
+    for (const issue of check.issues || []) console.log(`  - ${issue}`);
+  }
+}
+
+function main(argv) {
+  const result = buildTrustScore(process.cwd());
+  if (argv.includes("--json")) console.log(JSON.stringify(result, null, 2));
+  else printHuman(result);
+  return result.status === "FAIL" ? 1 : 0;
+}
+
+module.exports = {
+  buildTrustScore,
+  inspectInstall,
+  inspectProject,
+  inspectContracts,
+  inspectLedger,
+  inspectDesign,
+  inspectEmployeeExperience,
+};
+
+if (require.main === module) process.exit(main(process.argv));

package/docs/onboarding.html

@@ -496,9 +496,10 @@
       <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-debug</dt><dd>Investigative debugging. Use when the failure is unclear and you need evidence before repair.</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,7 +522,7 @@
       <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">

package/guide.md

@@ -13,7 +13,7 @@
 
 **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).
 
@@ -25,7 +25,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 35 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-vibe` for fast layout-preserving aesthetic pivots.
 
 ## The Road
 
@@ -91,6 +91,7 @@ Append `--auto` to `/qualia-new` and the framework chains every step:
 | 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 |
+| Planning hygiene | `qualia-framework planning-hygiene scan` | Detect loose `.planning/` reports/assets before they turn into folder bloat |
 | Hook gen | `/qualia-hook-gen` | Convert a CLAUDE.md/rules instruction into a deterministic hook (v5.3+) |
 | Road view | `/qualia-road` | View and navigate journey/milestone/phase status |
 | Lost? | `/qualia` | Mechanical next-command router |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "6.2.9",
+  "version": "6.2.10",
   "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-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-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/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/skills/qualia/SKILL.md

@@ -17,7 +17,7 @@ Read project state. Classify your situation. Tell you the exact next command.
 ### 1. Get State
 
 ```bash
-node ~/.claude/bin/state.js check 2>/dev/null
+node ${QUALIA_BIN}/state.js check 2>/dev/null
 ```
 
 Also gather context:
@@ -50,8 +50,8 @@ Use the state.js JSON output plus gathered context:
 | `polished` | status == "polished" | → `/qualia-ship` |
 | `shipped` | status == "shipped" | → `/qualia-handoff` |
 | `handed-off` | status == "handed_off" | → `/qualia-report` then done |
-| `blocked` | STATE.md lists blockers or same error 3+ times | → Analyze, suggest `/qualia-debug` |
-| `bug-loop` | Same files edited 3+ times, user frustrated | → Different approach, `/qualia-debug` |
+| `blocked` | STATE.md lists blockers or same error 3+ times | → Analyze; `/qualia-fix` if expected behavior is known, `/qualia-debug` if not |
+| `bug-loop` | Same files edited 3+ times, user frustrated | → Different approach, `/qualia-fix` if actionable, `/qualia-debug` if evidence is missing |
 | `need-tests` | User mentions "tests", "coverage", "test this" | → `/qualia-test` |
 
 **Employee escalation:** If role is EMPLOYEE and situation is `gap-limit` or `bug-loop`, suggest: "Want to flag this for Fawzi?"
@@ -60,16 +60,16 @@ Use the state.js JSON output plus gathered context:
 
 **Clear next step** (use the UI helper — it reads state.js itself):
 ```bash
-node ~/.claude/bin/qualia-ui.js banner router
+node ${QUALIA_BIN}/qualia-ui.js banner router
 # If a project is loaded, show the journey position first (one-glance orientation)
-test -f .planning/JOURNEY.md && node ~/.claude/bin/qualia-ui.js journey-tree .planning/JOURNEY.md
-node ~/.claude/bin/qualia-ui.js next "{next_command from state.js}"
+test -f .planning/JOURNEY.md && node ${QUALIA_BIN}/qualia-ui.js journey-tree .planning/JOURNEY.md
+node ${QUALIA_BIN}/qualia-ui.js next "{next_command from state.js}"
 ```
 
 **Ambiguous situation (multiple options):**
 Print the banner first, then use plain markdown for the options:
 ```bash
-node ~/.claude/bin/qualia-ui.js banner router
+node ${QUALIA_BIN}/qualia-ui.js banner router
 ```
 ```
 ## Where You Are
@@ -87,9 +87,9 @@ node ~/.claude/bin/qualia-ui.js banner router
 
 **Blocker detected** (gap-limit, bug-loop, employee escalation):
 ```bash
-node ~/.claude/bin/qualia-ui.js banner router
-node ~/.claude/bin/qualia-ui.js fail "{blocker description}"
-node ~/.claude/bin/qualia-ui.js warn "Escalate to Fawzi or re-plan from scratch"
+node ${QUALIA_BIN}/qualia-ui.js banner router
+node ${QUALIA_BIN}/qualia-ui.js fail "{blocker description}"
+node ${QUALIA_BIN}/qualia-ui.js warn "Escalate to Fawzi or re-plan from scratch"
 ```
 
 User can respond with a number, "just do it", or natural language.

package/skills/qualia-build/SKILL.md

@@ -32,9 +32,11 @@ Per `rules/codex-goal.md` — set the thread goal at phase start with scope `pha
 
 ```bash
 cat .planning/phase-{N}-plan.md
+cat .planning/phase-{N}-contract.json
+node ${QUALIA_BIN}/plan-contract.js validate .planning/phase-{N}-contract.json
 ```
 
-Parse tasks, waves, file refs.
+Parse tasks, waves, file refs. Prefer the JSON contract for task ids, dependencies, file lists, and verification checks; use the Markdown plan as the human-readable context.
 
 ### 1b. Recovery Reference
 
@@ -45,7 +47,7 @@ git tag -f "pre-build-phase-{N}" HEAD 2>/dev/null
 ```
 
 ```bash
-node ~/.claude/bin/qualia-ui.js info "Recovery point: pre-build-phase-{N}"
+node ${QUALIA_BIN}/qualia-ui.js info "Recovery point: pre-build-phase-{N}"
 ```
 
 Wave fail → stop, inspect status + output. Preserve work; fix forward or ask before reverting.
@@ -57,19 +59,19 @@ git diff --stat
 ### 2. Execute Waves
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner build {N} "{phase name}"
+node ${QUALIA_BIN}/qualia-ui.js banner build {N} "{phase name}"
 ```
 
 **For each wave (sequential):**
 
 ```bash
-node ~/.claude/bin/qualia-ui.js wave {W} {total_waves} {tasks_in_wave}
+node ${QUALIA_BIN}/qualia-ui.js wave {W} {total_waves} {tasks_in_wave}
 ```
 
 **Per task in wave: spawn ALL as separate `Agent()` calls in SAME turn (concurrent). Do NOT await one before spawning next.**
 
 ```bash
-node ~/.claude/bin/qualia-ui.js task {task_num} "{task title}"
+node ${QUALIA_BIN}/qualia-ui.js task {task_num} "{task title}"
 ```
 
 **Pre-inline context** (saves 3-5 Read calls per builder):
@@ -84,7 +86,7 @@ Spawn builder:
 
 ```
 Agent(prompt="
-Role: @~/.claude/agents/builder.md
+Role: @${QUALIA_AGENTS}/builder.md
 
 <phase_context>
 # PROJECT.md
@@ -110,6 +112,10 @@ Parallel tasks Wave {W} (do NOT touch their files):
 {task block from plan: title, wave, persona, files, depends-on, why, AC, action, validation, context}
 </task>
 
+<task_contract>
+{matching task object from .planning/phase-{N}-contract.json}
+</task_contract>
+
 Context tags already loaded. Only Read project code you modify.
 Execute. Commit. Return DONE/BLOCKED/PARTIAL.
 ", subagent_type="qualia-builder", description="Task {N}: {title}")
@@ -121,7 +127,7 @@ Execute. Commit. Return DONE/BLOCKED/PARTIAL.
 - Verify commit: `git log --oneline -1`
 - Show:
 ```bash
-node ~/.claude/bin/qualia-ui.js done {task_num} "{title}" {commit_hash}
+node ${QUALIA_BIN}/qualia-ui.js done {task_num} "{title}" {commit_hash}
 ```
 
 **After each wave:** move to next, show summary.
@@ -131,10 +137,10 @@ node ~/.claude/bin/qualia-ui.js done {task_num} "{title}" {commit_hash}
 All waves done:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js ok "Tasks: {done}/{total}"
-node ~/.claude/bin/qualia-ui.js ok "Commits: {count}"
-node ~/.claude/bin/qualia-ui.js ok "Waves: {count}"
+node ${QUALIA_BIN}/qualia-ui.js divider
+node ${QUALIA_BIN}/qualia-ui.js ok "Tasks: {done}/{total}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Commits: {count}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Waves: {count}"
 ```
 
 ### 4. Handle Failures
@@ -147,7 +153,7 @@ Builder returns deviation/blocker:
 ### 5. Update State
 
 ```bash
-node ~/.claude/bin/state.js transition --to built --phase {N} --tasks-done {done} --tasks-total {total} --wave {wave}
+node ${QUALIA_BIN}/state.js transition --to built --phase {N} --tasks-done {done} --tasks-total {total} --wave {wave}
 ```
 Error → show, stop.
 Do NOT edit STATE.md or tracking.json manually; state.js handles both.
@@ -157,7 +163,7 @@ Do NOT edit STATE.md or tracking.json manually; state.js handles both.
 **`--auto`:** invoke `/qualia-verify {N} --auto` inline. No pause.
 
 ```bash
-node ~/.claude/bin/qualia-ui.js info "Auto mode — chaining into /qualia-verify {N}"
+node ${QUALIA_BIN}/qualia-ui.js info "Auto mode — chaining into /qualia-verify {N}"
 ```
 
 Then invoke `qualia-verify` inline with `--auto`.
@@ -165,5 +171,5 @@ Then invoke `qualia-verify` inline with `--auto`.
 **Guided mode:** stop, show next step:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "PHASE {N} BUILT" "/qualia-verify {N}"
+node ${QUALIA_BIN}/qualia-ui.js end "PHASE {N} BUILT" "/qualia-verify {N}"
 ```