qualia-framework 6.2.10 → 6.3.0

package/skills/qualia/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia
-description: "Smart router — reads project state (state.js), classifies the situation mechanically, returns the exact next command. Use whenever you type /qualia, 'what next', 'next', 'what now', 'what should I do next', 'what command now'. For deeper 'I don't understand what's going on' / 'something feels off' situations, use /qualia-idk instead — that one actually scans the planning folder and codebase to diagnose the confusion."
+description: "Smart router — reads project state (state.js), classifies the situation mechanically, and either returns the exact next command or performs the lightweight diagnosis previously split across helper commands. Use whenever you type /qualia, 'what next', 'next', 'what now', 'what should I do next', 'what command now', 'resume', 'pause', or 'I don't know what is going on'."
 allowed-tools:
   - Bash
   - Read
@@ -39,7 +39,7 @@ Use the state.js JSON output plus gathered context:
 |-----------|-----------|-------|
 | `no-project` | state.js returns NO_PROJECT | → `/qualia-new` |
 | `handoff` | `.continue-here.md` exists | → Read it, summarize, route to next step |
-| `mid-work` | Uncommitted changes + phase in progress | → Continue or `/qualia-pause` |
+| `mid-work` | Uncommitted changes + phase in progress | → Continue, or write `.continue-here.md` if the user wants to pause |
 | `ready-to-plan` | status == "setup" | → `/qualia-plan {N}` |
 | `ready-to-build` | status == "planned" | → `/qualia-build {N}` |
 | `ready-to-verify` | status == "built" | → `/qualia-verify {N}` |
@@ -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; `/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 |
+| `blocked` | STATE.md lists blockers or same error 3+ times | → Diagnose the evidence; `/qualia-fix` if expected behavior is known, `/qualia-review` if broader audit is needed |
+| `bug-loop` | Same files edited 3+ times, user frustrated | → Stop patching; summarize root cause evidence and route to `/qualia-fix` or `/qualia-review` |
 | `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?"

package/skills/qualia-feature/SKILL.md

@@ -35,7 +35,7 @@ One command for adding a small new capability outside the planned Road. Auto-det
 - 5+ files or multiple subsystems touched → `/qualia-plan`
 - Part of a planned phase → `/qualia-build`
 - Broken existing behavior, regression, failing test, or hotfix → `/qualia-fix`
-- Investigating a symptom you can't name yet → `/qualia-debug`
+- Investigating a symptom you can't name yet → `/qualia-review`
 - Optimization or polish pass → `/qualia-optimize` or `/qualia-polish`
 
 ## Process

package/skills/qualia-fix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-fix
-description: "Practical repair lane for broken existing behavior. Blends /qualia-debug root-cause discipline with /qualia-feature execution. Use when the user says 'fix this', 'bug', 'broken', 'error', 'failing test', 'regression', 'hotfix', 'not working', 'layout broken', 'slow page', or 'config is wrong'."
+description: "Practical repair lane for broken existing behavior. Combines root-cause investigation with /qualia-feature execution discipline. Use when the user says 'fix this', 'bug', 'broken', 'error', 'failing test', 'regression', 'hotfix', 'not working', 'layout broken', 'slow page', or 'config is wrong'."
 allowed-tools:
   - Bash
   - Read
@@ -14,7 +14,7 @@ argument-hint: "[--quick|--frontend|--perf|--test|--no-commit] <symptom>"
 
 # /qualia-fix - Repair Broken Existing Behavior
 
-Fix is the practical lane for "this used to work, or should work, and now it does not." It combines the evidence discipline of `/qualia-debug` with the small-work execution path of `/qualia-feature`.
+Fix is the practical lane for "this used to work, or should work, and now it does not." It combines root-cause evidence gathering with the small-work execution path of `/qualia-feature`.
 
 ## Usage
 
@@ -38,9 +38,9 @@ Fix is the practical lane for "this used to work, or should work, and now it doe
 - Net-new capability -> `/qualia-feature`
 - Phase-sized work or 5+ likely files -> `/qualia-plan`
 - Read-only audit -> `/qualia-review`
-- No concrete symptom and no failing command -> `/qualia-debug`
+- No concrete symptom and no failing command -> `/qualia-review`
 - Visual craft/design quality with no functional bug -> `/qualia-polish`
-- Whole-site aesthetic pivot -> `/qualia-vibe`
+- Whole-site aesthetic pivot -> `/qualia-polish --vibe`
 
 ## Process
 

package/skills/qualia-learn/SKILL.md

@@ -122,7 +122,7 @@ node ${QUALIA_BIN}/knowledge.js list
 node ${QUALIA_BIN}/knowledge.js search "RLS"
 ```
 
-The `/qualia-debug` skill should check `common-fixes.md` (`load fixes`) before
+The `/qualia-fix` skill should check `common-fixes.md` (`load fixes`) before
 investigating. The `/qualia-new` skill should check `client-prefs.md`
 (`load client`) when setting up client projects. The `/qualia-plan` skill
 should check `learned-patterns.md` (`load patterns`) when planning phases.

package/skills/qualia-polish/REFERENCE.md

@@ -262,6 +262,6 @@ This is intentional. Most visual regressions Fawzi has documented in `/insights`
 - Accessibility audits beyond what the rubric scores — use `/qualia-polish` Stage 3 (Lighthouse + axe) for that.
 - Performance regressions — use `/qualia-polish --loop` only after Lighthouse score passes.
 - Reference-image-only mode (compare to a target screenshot without a brief) — the brief is required; reference is supplemental.
-- Aesthetic pivots — if the issue is "the whole vibe is wrong", `/qualia-vibe` swaps the aesthetic in minutes instead of grinding the loop against a vibe that doesn't fit.
+- Aesthetic pivots — if the issue is "the whole vibe is wrong", `/qualia-polish --vibe` swaps the aesthetic in minutes instead of grinding the loop against a vibe that doesn't fit.
 
 Implemented as of v5.2: `--routes a,b,c` for multi-route sweeps, `--reduced-motion` for `prefers-reduced-motion: reduce` capture.

package/skills/qualia-polish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-polish
-description: "Scope-adaptive visual quality pass. Works on a single component, a route, the whole app, a ground-up redesign, or an autonomous visual loop, but does not repair business logic or broken data flow. Trigger on 'polish', 'design pass', 'fix the design', 'redesign', 'critique', 'audit design', 'looks ugly', 'make it look better', 'polish loop', 'visual loop', 'fix what I see', 'iterate on the design until it's correct'. Route functional bugs to /qualia-fix and aesthetic token pivots to /qualia-vibe."
+description: "Scope-adaptive visual quality pass. Works on a single component, a route, the whole app, a ground-up redesign, an aesthetic token pivot, or an autonomous visual loop, but does not repair business logic or broken data flow. Trigger on 'polish', 'design pass', 'fix the design', 'redesign', 'critique', 'audit design', 'looks ugly', 'make it look better', 'different vibe', 'polish loop', 'visual loop', 'fix what I see', 'iterate on the design until it's correct'. Route functional bugs to /qualia-fix."
 allowed-tools:
   - Bash
   - Read
@@ -18,7 +18,7 @@ argument-hint: "[file|route|--redesign|--critique|--quick|--loop] [--register=br
 
 One command. Seven scopes. Use it whenever you need design work, from a 30-second component touch-up to a ground-up redesign with current design research, complex visuals, and a fully transparent see-fix-verify loop.
 
-Polish fixes visual quality only. Broken behavior, failing tests, API bugs, state bugs, and config errors go to `/qualia-fix`. Whole-site aesthetic token pivots go to `/qualia-vibe`.
+Polish fixes visual quality only. Broken behavior, failing tests, API bugs, state bugs, and config errors go to `/qualia-fix`. Whole-site aesthetic token pivots stay inside `/qualia-polish --vibe` so the design surface is one command.
 
 ## Scopes
 
@@ -32,9 +32,10 @@ The first argument selects the scope. Stage selection follows from scope.
 | `/qualia-polish --redesign` | **Redesign** | ~30m | all + Stage 1 mandatory + 2 vision iterations |
 | `/qualia-polish --critique` | **Critique** | read-only | 0, 4, 5 (no edits) |
 | `/qualia-polish --quick` | **Quick** | ~1m | 0, 2, 7 (gates only, no vision loop) |
+| `/qualia-polish --vibe` | **Aesthetic pivot** | ~3m | token-only direction swap |
 | `/qualia-polish --loop {url}` | **Loop** | ~5-15m | autonomous see/fix/verify, max 8 iterations |
 
-Other flags: `--register=brand|product` overrides register inference. Loop-specific flags: `--brief PATH`, `--max N`, `--viewports 375,768,1440`, `--ref PATH`, `--budget 100000`.
+Other flags: `--register=brand|product` overrides register inference. Vibe-specific flags: `--variants N`, `--extract URL|image`, `--sync`, `--write`. Loop-specific flags: `--brief PATH`, `--max N`, `--viewports 375,768,1440`, `--ref PATH`, `--budget 100000`.
 
 ## Transparent Command Output
 
@@ -58,6 +59,20 @@ Scripts ship at `skills/qualia-polish/scripts/{loop,playwright-capture,score}.mj
 
 When `--loop` is detected on entry, route to the loop process documented in `REFERENCE.md` and stop executing the standard stages below. The two paths share Stage 0 substrate gates and the rubric, but diverge from Stage 1 onward.
 
+## --vibe mode (aesthetic token pivot)
+
+When `--vibe` is detected, do not restructure JSX, routes, data flow, navigation, or layout grids. Change only aesthetic tokens and matching DESIGN.md sections: color, typography, depth, motion, brand accents, and short visual-direction copy.
+
+Supporting scripts ship inside this skill:
+
+```bash
+node ${QUALIA_SKILLS}/qualia-polish/scripts/vibe-tokens.mjs sync --design .planning/DESIGN.md
+node ${QUALIA_SKILLS}/qualia-polish/scripts/vibe-tokens.mjs propose-variants --product .planning/PRODUCT.md --design .planning/DESIGN.md --count 3
+node ${QUALIA_SKILLS}/qualia-polish/scripts/vibe-extract.mjs --source https://example.com
+```
+
+Default flow proposes one opinionated direction per `rules/one-opinion.md`. `--variants` is opt-in only. `--extract` stages a reference screenshot for the visual evaluator to reverse-engineer into DESIGN.md tokens; the user must review low-confidence extracted values before application. `--sync --write` patches DESIGN.md to reflect tokens already present in code.
+
 ## Setup gates (non-optional, every scope)
 
 Before any work — design or otherwise — pass these gates. Skipping them produces generic output that ignores the project.
@@ -109,7 +124,7 @@ For Redesign scope, run a short online best-practices check before the brief unl
 
 Use the sources as constraints, not as a style to copy. Cite links in the report/summary when they shaped the redesign.
 
-If the user pushes back on the proposed direction, that is a `/qualia-vibe` trigger — switch surfaces, do not start enumerating alternatives in the brief.
+If the user pushes back on the proposed direction, switch to `/qualia-polish --vibe` mode — do not start enumerating alternatives in the brief.
 
 For Component / Section / Quick scope, the brief is implicit (loaded from DESIGN.md). Skip the ultrathink step but cite the relevant DESIGN.md tokens you'll touch.
 

package/skills/{qualia-vibe/scripts/extract.mjs → qualia-polish/scripts/vibe-extract.mjs}

@@ -6,11 +6,11 @@
  *   1. If source is a URL → capture screenshot at 1440 via playwright-capture.mjs.
  *      If source is a local image path → use it directly.
  *   2. Emit a JSON scaffold the LLM uses to generate the extracted token bundle.
- *   3. The skill (qualia-vibe) reads the scaffold, runs the vision evaluator in
+ *   3. The skill (qualia-polish --vibe) reads the scaffold, runs the vision evaluator in
  *      extract mode, gets the bundle back, renders it as a DESIGN.md draft.
  *
  * This script does NOT call any LLM directly — it stages the inputs and emits
- * a deterministic JSON contract. The /qualia-vibe skill orchestrates the LLM
+ * a deterministic JSON contract. The /qualia-polish --vibe skill orchestrates the LLM
  * call.
  *
  * Usage:
@@ -49,7 +49,7 @@ let screenshotPath;
 const isUrl = /^https?:\/\//i.test(source);
 if (isUrl) {
   const stamp = Date.now().toString(36);
-  const outDir = join(tmpdir(), `qualia-vibe-extract-${stamp}`);
+  const outDir = join(tmpdir(), `qualia-polish-vibe-extract-${stamp}`);
   mkdirSync(outDir, { recursive: true });
   screenshotPath = join(outDir, "ref-1440.png");
 
@@ -132,7 +132,7 @@ const scaffold = {
   rules: [
     "Banned fonts: Inter, Roboto, Arial, Helvetica, system-ui, Space Grotesk, Montserrat, Poppins, Lato, Open Sans. If you see one of these, name it AND flag it so the user can decide whether to ban or accept.",
     "Banned patterns: purple-blue gradient, gradient text, bounce/elastic easing. Flag the same way.",
-    "Confidence < high → user must review before /qualia-vibe applies.",
+    "Confidence < high → user must review before /qualia-polish --vibe applies.",
   ],
   next_step: `After producing the bundle, write a DESIGN.md draft to ${outDraft} using the bundle to populate sections 1 (Direction), 2 (Color), 3 (Typography), 4 (Spacing), 6 (Depth), 7 (Motion). Leave sections that depend on PRODUCT.md or anti-references empty — the user will fill them.`,
 };

package/skills/{qualia-vibe/scripts/tokens.mjs → qualia-polish/scripts/vibe-tokens.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * tokens.mjs — read/write design tokens for /qualia-vibe.
+ * tokens.mjs — read/write design tokens for /qualia-polish --vibe.
  *
  * Commands:
  *   tokens.mjs sync --design .planning/DESIGN.md [--write]
@@ -36,13 +36,13 @@ function hasFlag(name) {
 const CMD = argv[2];
 
 if (!CMD || CMD === "--help" || CMD === "-h") {
-  console.log(`tokens.mjs — design-token utility for /qualia-vibe
+  console.log(`tokens.mjs — design-token utility for /qualia-polish --vibe
 
 Usage:
   tokens.mjs sync --design <path> [--write]
   tokens.mjs propose-variants --product <path> --design <path> --count <N>
 
-See skills/qualia-vibe/SKILL.md.
+See skills/qualia-polish/SKILL.md.
 `);
   exit(0);
 }
@@ -268,7 +268,7 @@ function cmdSync() {
       ``,
       `## §sync — auto-synced from code (${stamp})`,
       ``,
-      `<!-- Generated by /qualia-vibe --sync --write. Reflects values actually present in code at sync time. -->`,
+      `<!-- Generated by /qualia-polish --vibe --sync --write. Reflects values actually present in code at sync time. -->`,
       ``,
       "```css",
       `:root {`,
@@ -307,7 +307,7 @@ function cmdProposeVariants() {
 
   // Emit a structured scaffold the LLM uses to generate variants.
   const scaffold = {
-    instruction: `Generate exactly ${count} aesthetic-direction variants for /qualia-vibe --variants. Each variant must be opinionated and concrete — no "modern minimal" hedging. Variants must be meaningfully different from each other AND from the current direction.`,
+    instruction: `Generate exactly ${count} aesthetic-direction variants for /qualia-polish --vibe --variants. Each variant must be opinionated and concrete — no "modern minimal" hedging. Variants must be meaningfully different from each other AND from the current direction.`,
     context: {
       product_md: product.slice(0, 4000),
       current_direction_lines: design
@@ -323,7 +323,7 @@ function cmdProposeVariants() {
       "No purple-blue gradients.",
       "No bounce/elastic easing.",
       `Respect anti-references from PRODUCT.md if present.`,
-      "Each variant should be commit-able as-is — concrete enough that /qualia-vibe can apply it without further questions.",
+      "Each variant should be commit-able as-is — concrete enough that /qualia-polish --vibe can apply it without further questions.",
     ],
   };
 

package/skills/qualia-road/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-road
-description: "TERMINAL workflow map — Project → Journey → Milestones → Phases → Tasks. Use this in headless/SSH/no-browser sessions or when the user asks for the road in chat. For the HTML reference (default when a browser is available), use /qualia-help. Triggers: 'how does Qualia work', 'what's the workflow', 'show me the road', 'what command does X', 'how do projects flow', 'in terminal please', SSH context."
+description: "TERMINAL workflow map — Project → Journey → Milestones → Phases → Tasks. Use this in headless/SSH/no-browser sessions or when the user asks for the road in chat. Triggers: 'how does Qualia work', 'what's the workflow', 'show me the road', 'what command does X', 'how do projects flow', 'in terminal please', SSH context."
 disable-model-invocation: true
 allowed-tools:
   - Read
@@ -45,17 +45,17 @@ Every road agent loads `PRODUCT.md + DESIGN.md + design-laws.md` substrate. Buil
 /qualia-polish --quick                       ~1m  gates only
 ```
 
-## Design pivots — /qualia-vibe (v6.1+)
+## Design pivots — /qualia-polish --vibe
 ```
-/qualia-vibe                              fast aesthetic pivot: ONE proposed direction, swap tokens, keep layout (~3 min)
-/qualia-vibe brutalist                    explicit pivot to named direction
-/qualia-vibe --variants 3                 opt-in menu (uses AskUserQuestion; default flow is one-opinion)
-/qualia-vibe --extract https://stripe.com reverse-engineer DESIGN.md from a reference URL
-/qualia-vibe --extract ./inspo.png        same, from a local screenshot
-/qualia-vibe --sync                       show drift between code (CSS vars, Tailwind config) and DESIGN.md
-/qualia-vibe --sync --write               patch DESIGN.md to match code, commit
+/qualia-polish --vibe                              fast aesthetic pivot: ONE proposed direction, swap tokens, keep layout (~3 min)
+/qualia-polish --vibe brutalist                    explicit pivot to named direction
+/qualia-polish --vibe --variants 3                 opt-in menu (rare; default flow is one-opinion)
+/qualia-polish --vibe --extract https://stripe.com reverse-engineer DESIGN.md from a reference URL
+/qualia-polish --vibe --extract ./inspo.png        same, from a local screenshot
+/qualia-polish --vibe --sync                       show drift between code (CSS vars, Tailwind config) and DESIGN.md
+/qualia-polish --vibe --sync --write               patch DESIGN.md to match code, commit
 ```
-`/qualia-vibe` is for the WHOLE-SITE aesthetic. For surgical component-level fixes use `/qualia-polish` (component or section scope). For ground-up structural redesign use `/qualia-polish --redesign`.
+`/qualia-polish --vibe` is for the WHOLE-SITE aesthetic. For surgical component-level fixes use `/qualia-polish` (component or section scope). For ground-up structural redesign use `/qualia-polish --redesign`.
 
 ## /qualia-polish --loop — autonomous visual QA
 ```
@@ -69,21 +69,17 @@ Screenshots at 3 viewports (375/768/1440), scores 9 design dimensions using visi
 
 ## Deterministic-enforcement skills
 ```
-/qualia-hook-gen       convert a CLAUDE.md/rules instruction into a deterministic pre-tool-use hook
 /qualia-optimize --deepen   spawns 3 parallel interface-design variants per candidate (Step 5b)
 ```
-`/qualia-hook-gen` reduces lifetime token cost (each migrated rule frees ~50-200 tokens per request). `/qualia-optimize --deepen` produces dramatically better refactor RFCs because 3 radically-different interfaces are surfaced and the human picks/hybridizes.
+`/qualia-optimize --deepen` produces dramatically better refactor RFCs because 3 radically-different interfaces are surfaced and the human picks/hybridizes.
 
 ## Alignment substrate
 Before high-stakes phases, run alignment skills against `.planning/CONTEXT.md` (domain glossary) and `.planning/decisions/` (ADRs):
 
 ```
 /qualia-discuss            → relentless one-question interview, updates CONTEXT.md inline
-/qualia-zoom               → map an unfamiliar code area using glossary terms
 /qualia-optimize --deepen  → find shallow modules, propose Ousterhout-style refactors
 /qualia-test --tdd         → vertical-slice red→green→refactor for one feature
-/qualia-issues             → break a phase plan into independent GH issues
-/qualia-triage             → label + route open issues (ready-for-agent vs human)
 /qualia-map                → adapt Qualia to an existing brownfield repo's conventions (5th onboarding agent)
 ```
 
@@ -91,23 +87,22 @@ Before high-stakes phases, run alignment skills against `.planning/CONTEXT.md` (
 ```
 Lost?        → /qualia        (state router — tells you the next command)
 Health?      → /qualia-doctor (install, state, contracts, memory, ERP queue)
-Stuck/weird? → /qualia-idk    (diagnostic — spawns plan-view + code-view agents in parallel)
+Stuck/weird? → /qualia        (diagnostic branch — scans planning + code when state alone is insufficient)
 Broken thing? → /qualia-fix     (root cause, minimal patch, verify, report)
 Single feature? → /qualia-feature (new capability: inline for trivia, fresh spawn for 1-5 files)
-Paused?      → /qualia-resume (restore from .continue-here.md or STATE.md)
+Paused?      → /qualia        (restore from .continue-here.md or STATE.md)
 End of day?  → /qualia-report (mandatory before clock-out; writes ERP payload)
-Debug why?   → /qualia-debug  (feedback-loop-first investigation when evidence is unclear)
 Unsure plan? → /qualia-discuss (capture decisions before planning)
 ```
 
 ## Outside-road command boundaries
 ```
 Need a repair?       → /qualia-fix       (mutates code, proves fix)
-Need an investigation? → /qualia-debug   (evidence first, no guessing)
+Need an investigation? → /qualia-review  (read-only audit) or /qualia-fix (known broken behavior)
 Need an audit?       → /qualia-review    (detect-only, scored findings)
 Need improvement map? → /qualia-optimize (report/RFC, broad opportunities)
 Need visual quality? → /qualia-polish    (style/layout/accessibility)
-Need new aesthetic?  → /qualia-vibe      (tokens only, layout preserved)
+Need new aesthetic?  → /qualia-polish --vibe (tokens only, layout preserved)
 Need new capability? → /qualia-feature   (small net-new work)
 ```
 

package/skills/qualia-ship/SKILL.md

@@ -32,6 +32,14 @@ fi
 
 STATUS=$(echo "$STATE" | node -e "try{const d=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(d.status||'')}catch{}")
 VERIFICATION=$(echo "$STATE" | node -e "try{const d=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(d.verification||'')}catch{}")
+NEXT_COMMAND=$(echo "$STATE" | node -e "try{const d=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(d.next_command||'/qualia')}catch{process.stdout.write('/qualia')}")
+ROLE=$(node -e "try{const fs=require('fs'),path=require('path'),os=require('os');const h=process.env.QUALIA_HOME||path.dirname(process.env.QUALIA_BIN||path.join(os.homedir(),'.claude','bin'));const c=JSON.parse(fs.readFileSync(path.join(h,'.qualia-config.json'),'utf8'));process.stdout.write((c.role||'').toUpperCase())}catch{}")
+
+if [ "${QUALIA_SHIP_FORCE:-0}" = "1" ] && [ "$ROLE" != "OWNER" ]; then
+  node ${QUALIA_BIN}/qualia-ui.js fail "Owner override is OWNER-only."
+  node ${QUALIA_BIN}/qualia-ui.js info "Run $NEXT_COMMAND."
+  exit 1
+fi
 
 # Valid ship-from states:
 #   polished     — /qualia-polish ran cleanly; ready for deploy
@@ -41,10 +49,9 @@ if [ "$STATUS" != "polished" ] && ! { [ "$STATUS" = "verified" ] && [ "$VERIFICA
   if [ "${QUALIA_SHIP_FORCE:-0}" = "1" ]; then
     node ${QUALIA_BIN}/qualia-ui.js warn "Forced ship from state '$STATUS' (verification: ${VERIFICATION:-none}). Record the reason in the final report."
   else
-  node ${QUALIA_BIN}/qualia-ui.js fail "Cannot ship from state '$STATUS' (verification: ${VERIFICATION:-none})."
-  node ${QUALIA_BIN}/qualia-ui.js info "Run /qualia-polish first, or /qualia-verify {phase} if verification is still pending."
-  node ${QUALIA_BIN}/qualia-ui.js info "Hotfix override: set QUALIA_SHIP_FORCE=1 only when the user explicitly approved it."
-  exit 1
+    node ${QUALIA_BIN}/qualia-ui.js fail "Ship refused from state '$STATUS' (verification: ${VERIFICATION:-none})."
+    node ${QUALIA_BIN}/qualia-ui.js info "Run $NEXT_COMMAND."
+    exit 1
   fi
 fi
 ```
@@ -64,7 +71,7 @@ On failure:
 1. Summarize what failed in plain language
 2. Auto-fix
 3. Re-run the gate
-4. If still failing after 2 attempts: tell the employee, suggest `/qualia-debug`
+4. If still failing after 2 attempts: tell the employee, suggest `/qualia-fix`
 
 ### 2. Security Check — full depth
 

package/skills/qualia-verify/SKILL.md

@@ -169,8 +169,16 @@ node ${QUALIA_BIN}/qualia-ui.js end "PHASE {N} GAPS FOUND" "/qualia-plan {N} --g
 
 ### 4. Update State
 
+Write the deterministic eval artifact before changing state:
+
+```bash
+node ${QUALIA_BIN}/harness-eval.js --phase {N} --run --write
+```
+
+If the eval status is `FAIL`, do not mark the phase PASS. The state machine also refuses PASS when a contract exists but `.planning/evidence/phase-{N}-contract-run.json` is missing/failing, or when the verification report contains `INSUFFICIENT EVIDENCE`.
+
 ```bash
-node ${QUALIA_BIN}/state.js transition --to verified --phase {N} --verification {pass|fail}
+node ${QUALIA_BIN}/state.js transition --to verified --phase {N} --verification {pass|fail} --evidence .planning/evals/harness-eval-*.json
 ```
 PASS + more phases → state.js auto-advances.
 FAIL + gap_cycles >= limit → GAP_CYCLE_LIMIT, escalate.

package/templates/help.html

@@ -364,13 +364,9 @@
       <div class="commands">
         <div class="cmd"><span class="cmd-name">/qualia-doctor</span><span class="cmd-desc">Framework health check &mdash; install, state, contracts, memory, hooks, and ERP queue. Use when Qualia itself feels broken or Codex/Claude is not picking it up.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-fix</span><span class="cmd-desc">Repair broken existing behavior &mdash; build a feedback loop, find root cause, patch minimally, verify, write a fix report. Trigger on 'fix this', 'bug', 'broken', 'failing test', 'regression'.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-debug</span><span class="cmd-desc">Structured investigation &mdash; symptom gathering, diagnosis confirmation, root cause analysis. Use when the failure is unclear and you need evidence before repair.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-review</span><span class="cmd-desc">Read-only production audit with scored diagnostics. Runs real commands, scores findings by severity, then routes repairs to /qualia-fix, /qualia-polish, or /qualia-optimize.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-optimize</span><span class="cmd-desc">Deep improvement discovery &mdash; reads .planning/ AND codebase to find performance, design, UI, backend, alignment, and architecture opportunities. Writes OPTIMIZE.md/RFCs; specific repairs route through /qualia-fix.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-test</span><span class="cmd-desc">Generate or run tests for client projects. Trigger on 'write tests', 'add tests', 'test this', 'test coverage'.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-zoom</span><span class="cmd-desc">Focus on a single file or function with full context (glossary terms, depending callers, ADRs touched). Use when a fresh agent needs surgical context for a tricky area.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-issues</span><span class="cmd-desc">Break a phase plan into independent vertical-slice GitHub issues with needs-triage label. Externalizes work to the open queue so other sessions or contributors can pull from it.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-triage</span><span class="cmd-desc">State machine over open GH issues — labels each as needs-triage, needs-info, ready-for-agent, ready-for-human, or wontfix. Pairs with /qualia-issues for the autonomous queue.</span></div>
       </div>
     </div>
 
@@ -381,7 +377,7 @@
       <div class="commands">
         <div class="cmd"><span class="cmd-name">/qualia-feature</span><span class="cmd-desc">Auto-scoped new-feature build. Inline for trivia (copy, config), fresh builder spawn for 1-5 file features. Broken existing behavior routes to /qualia-fix. Flags: --force-spawn, --force-inline.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-polish</span><span class="cmd-desc">Visual quality pass, scope-adaptive &mdash; component, route, full app, redesign, critique, quick. It fixes style/layout/accessibility only; functional bugs route to /qualia-fix.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-vibe</span><span class="cmd-desc">Fast aesthetic-token pivot (~3 min) &mdash; swap color, type, depth, and motion, keep layout untouched. Structural redesign routes to /qualia-polish --redesign.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-polish --vibe</span><span class="cmd-desc">Fast aesthetic-token pivot (~3 min) &mdash; swap color, type, depth, and motion, keep layout untouched. Structural redesign routes to /qualia-polish --redesign.</span></div>
       </div>
     </div>
 
@@ -391,7 +387,6 @@
       <p class="cmd-group-note">Persist learnings and log work.</p>
       <div class="commands">
         <div class="cmd"><span class="cmd-name">/qualia-learn</span><span class="cmd-desc">Save a learning, pattern, fix, or client preference to the knowledge base. Persists across projects and sessions.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-flush</span><span class="cmd-desc">Promote raw daily logs into curated knowledge concepts. Use weekly or when session logs contain durable lessons.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-report</span><span class="cmd-desc">Generate session report and commit to repo. Mandatory before clock-out.</span></div>
       </div>
     </div>
@@ -401,8 +396,6 @@
       <h3>Session</h3>
       <p class="cmd-group-note">Hand off and resume context cleanly.</p>
       <div class="commands">
-        <div class="cmd"><span class="cmd-name">/qualia-pause</span><span class="cmd-desc">Save session context for seamless handoff. Creates .continue-here.md so the next session picks up exactly where you left off.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-resume</span><span class="cmd-desc">Restore context from a previous session. Reads .continue-here.md or STATE.md, summarizes where you left off, routes to next action.</span></div>
       </div>
     </div>
 
@@ -412,8 +405,6 @@
       <p class="cmd-group-note">When you don't know what to do next.</p>
       <div class="commands">
         <div class="cmd"><span class="cmd-name">/qualia</span><span class="cmd-desc">Smart router &mdash; reads project state, classifies your situation, tells you the exact next command. Use whenever you're unsure about your next step.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-idk</span><span class="cmd-desc">Diagnostic intelligence &mdash; spawns two isolated scans (planning + codebase) in parallel, cross-references against your confusion, explains the situation in plain language with a concrete next step. Use when something feels off or you need to understand what's going on.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-help</span><span class="cmd-desc">Open the Qualia Framework reference guide in the browser. A beautiful themed HTML page with all commands, rules, services, and the road.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-road</span><span class="cmd-desc">Terminal workflow map — Project → Journey → Milestones → Phases → Tasks. Use in headless/SSH sessions or when you want the road in chat instead of the browser.</span></div>
       </div>
     </div>
@@ -423,9 +414,7 @@
       <h3>Meta</h3>
       <p class="cmd-group-note">Extend the framework itself.</p>
       <div class="commands">
-        <div class="cmd"><span class="cmd-name">/qualia-skill-new</span><span class="cmd-desc">Author a new Qualia skill or agent. Generates the SKILL.md, registers it in the right location, and optionally ships to the framework repo.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-postmortem</span><span class="cmd-desc">Analyze a verification failure and turn the lesson into a framework improvement.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-hook-gen</span><span class="cmd-desc">Convert a CLAUDE.md or rules instruction into a deterministic Claude Code pre-tool-use hook. Lets you shrink your instruction budget instead of just hearing the advice.</span></div>
         <div class="cmd"><span class="cmd-name">/zoho-workflow</span><span class="cmd-desc">Internal Qualia Solutions ops — Zoho Invoice and Mail integration via ERP-first routing.</span></div>
       </div>
     </div>