qualia-framework 6.2.7 → 6.2.10

package/skills/qualia-build/SKILL.md

@@ -24,13 +24,19 @@ Execute phase plan. Each task = fresh subagent. Independent tasks run parallel.
 
 ## Process
 
+### 0. Codex goal (Codex runtime only)
+
+Per `rules/codex-goal.md` — set the thread goal at phase start with scope `phase`.
+
 ### 1. Load Plan
 
 ```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
 
@@ -41,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.
@@ -53,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):
@@ -80,7 +86,7 @@ Spawn builder:
 
 ```
 Agent(prompt="
-Role: @~/.claude/agents/builder.md
+Role: @${QUALIA_AGENTS}/builder.md
 
 <phase_context>
 # PROJECT.md
@@ -106,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}")
@@ -117,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.
@@ -127,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
@@ -143,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.
@@ -153,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`.
@@ -161,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}"
 ```

package/skills/qualia-debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-debug
-description: "Investigative debugging — parses symptom from arguments, runs diagnostic scans, identifies root cause, applies minimal fix, writes DEBUG report. Trigger on 'debug', 'find bug', 'fix error', 'something is broken', 'not working', 'weird behavior', 'layout broken', 'CSS issue', 'slow page', 'performance'."
+description: "Investigation lane for unclear bugs and weird behavior. Parses symptoms, runs diagnostic scans, identifies root cause, and either reports insufficient evidence or routes actionable repair work to /qualia-fix. Trigger on 'debug', 'find bug', 'why is this broken', 'something is weird', 'investigate', 'root cause', 'not sure what's failing', 'CSS issue', 'slow page', 'performance'."
 allowed-tools:
   - Bash
   - Read
@@ -13,7 +13,7 @@ allowed-tools:
 
 # /qualia-debug — Investigative Debugging (one-shot)
 
-Parse the symptom. Run diagnostics. Find root cause. Apply minimal fix. Write report. **One-shot — no mandatory user questions.**
+Parse the symptom. Run diagnostics. Find root cause. Write report, or route to `/qualia-fix` when the repair is actionable. **One-shot — no mandatory user questions.**
 
 ## Usage
 
@@ -22,6 +22,8 @@ Parse the symptom. Run diagnostics. Find root cause. Apply minimal fix. Write re
 - `/qualia-debug --frontend {symptom}` — layout/z-index/overflow bias
 - `/qualia-debug --perf {symptom}` — performance bias
 
+If the user says "fix it" and the expected behavior is known, prefer `/qualia-fix`. Debug is for uncertainty; fix is for repair.
+
 ## Tool Budget
 
 Max 10 Read/Grep/Bash calls for investigation. If you haven't narrowed to root cause in 10, return `INSUFFICIENT EVIDENCE after 10 steps. Narrowed to: {files}. Recommend: {next diagnostic}.` Do not keep guessing.
@@ -29,7 +31,7 @@ Max 10 Read/Grep/Bash calls for investigation. If you haven't narrowed to root c
 ## Process
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner debug
+node ${QUALIA_BIN}/qualia-ui.js banner debug
 ```
 
 ### 1. Parse Symptom from $ARGUMENTS
@@ -40,7 +42,7 @@ node ~/.claude/bin/qualia-ui.js banner debug
 ### 2. Check Known Fixes First (cheap)
 
 ```bash
-node ~/.claude/bin/knowledge.js search "{symptom_keywords}"
+node ${QUALIA_BIN}/knowledge.js search "{symptom_keywords}"
 ```
 
 If a known fix matches, apply it and jump to step 5 (verify). Known fixes are pre-verified patterns — no need to re-investigate.
@@ -97,10 +99,12 @@ grep -rn "import(\|next/dynamic" --include="*.tsx" --include="*.ts" app/ src/ 2>
 grep -rln "'use client'" --include="*.tsx" app/ components/ src/ 2>/dev/null | wc -l
 ```
 
-### 4. Form Hypothesis + Apply Minimal Fix
+### 4. Form Hypothesis + Route or Apply Minimal Fix
 
 From the diagnostic output, state the root cause in one sentence with `file:line` citation. No hedging — either you have evidence or you write `INSUFFICIENT EVIDENCE` and return (step 6).
 
+If the user explicitly asked for repair and the fix is <= 3 files, route to `/qualia-fix {symptom}` with the root cause summary. If this debug invocation is already mid-repair, apply the minimal fix here for backward compatibility.
+
 Apply the minimal fix:
 - Only edit files whose contents caused the symptom
 - One concept per commit — don't fold in cleanup
@@ -122,7 +126,11 @@ If the verification fails, revert and return to step 3 with narrower hypothesis.
 
 ### 6. Write DEBUG Report
 
-Write to `.planning/DEBUG-{YYYY-MM-DD-HHMM}.md`:
+Create the report directory and write to `.planning/reports/debug/DEBUG-{YYYY-MM-DD-HHMM}.md`:
+
+```bash
+mkdir -p .planning/reports/debug
+```
 
 ```markdown
 # Debug Report — {YYYY-MM-DD HH:MM}
@@ -180,6 +188,6 @@ Do NOT apply a speculative fix. Return the report and stop.
 
 - **No mandatory questions.** This is one-shot. If symptom args are missing, investigate recent changes.
 - **Root cause or INSUFFICIENT EVIDENCE** — no "probably" fixes.
-- **Minimal fix only.** One concept, one commit. No refactors dressed as debug.
+- **Minimal fix only.** One concept, one commit. No refactors dressed as debug. Prefer `/qualia-fix` for explicit repair requests.
 - **Tool budget is hard.** 10 calls, then stop.
-- **Every fix gets a DEBUG report in .planning/** — creates a searchable record.
+- **Every investigation gets a DEBUG report in `.planning/reports/debug/`** — creates a searchable record without cluttering the root.

package/skills/qualia-discuss/SKILL.md

@@ -64,7 +64,7 @@ This is the only fork. Demo runs §1-§8 of the discovery template. Full project
 ### P2. Banner and open
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner discuss-project
+node ${QUALIA_BIN}/qualia-ui.js banner discuss-project
 ```
 
 Say: **"Eight quick questions for the demo path"** or **"Fourteen questions to shape the full project — we'll move fast"** depending on type.
@@ -85,20 +85,20 @@ Allowed `[Enter]` defaults exist on §2, §3, §5 only (inferred from project ty
 
 ### P4. Write `.planning/project-discovery.md`
 
-Fill the template at `~/.claude/qualia-templates/project-discovery.md` with the user's verbatim answers. Set frontmatter `project_type` and `discovered_at`.
+Fill the template at `${QUALIA_TEMPLATES}/project-discovery.md` with the user's verbatim answers. Set frontmatter `project_type` and `discovered_at`.
 
 ### P5. Hand back to `/qualia-new`
 
 ```bash
 git add .planning/project-discovery.md
 git commit -m "docs: project discovery interview ($PROJECT_TYPE)"
-node ~/.claude/bin/qualia-ui.js ok "Discovery captured — back to /qualia-new"
+node ${QUALIA_BIN}/qualia-ui.js ok "Discovery captured — back to /qualia-new"
 ```
 
 If invoked standalone (not from `/qualia-new`), end with:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "DISCOVERY CAPTURED" "/qualia-new"
+node ${QUALIA_BIN}/qualia-ui.js end "DISCOVERY CAPTURED" "/qualia-new"
 ```
 
 If invoked inline by `/qualia-new`, return control silently — `/qualia-new` continues from Step 2.
@@ -135,19 +135,19 @@ Surface and lock the decisions, trade-offs, and constraints that must inform a p
 ### 1. Load substrate
 
 ```bash
-node ~/.claude/bin/state.js check 2>/dev/null
+node ${QUALIA_BIN}/state.js check 2>/dev/null
 cat .planning/PROJECT.md .planning/ROADMAP.md .planning/CONTEXT.md 2>/dev/null
 ls .planning/decisions/ 2>/dev/null
 cat .planning/research/SUMMARY.md 2>/dev/null
 ```
 
-If `.planning/CONTEXT.md` is missing, copy `~/.claude/qualia-templates/CONTEXT.md` to `.planning/CONTEXT.md` first.
-If `.planning/decisions/` is missing, create it. Copy `~/.claude/qualia-templates/decisions/ADR-template.md` next to it for reference.
+If `.planning/CONTEXT.md` is missing, copy `${QUALIA_TEMPLATES}/CONTEXT.md` to `.planning/CONTEXT.md` first.
+If `.planning/decisions/` is missing, create it. Copy `${QUALIA_TEMPLATES}/decisions/ADR-template.md` next to it for reference.
 
 ### 2. Open the conversation
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner discuss {N} "{phase name from ROADMAP.md}"
+node ${QUALIA_BIN}/qualia-ui.js banner discuss {N} "{phase name from ROADMAP.md}"
 ```
 
 Then state the goal in one sentence and the open questions you found in priority order (highest-stakes / hardest-to-reverse first).
@@ -200,14 +200,14 @@ Loop until "Lock it in".
 
 ### 6. Write phase-{N}-context.md
 
-Fill `~/.claude/qualia-templates/phase-context.md` with concrete content. Reference any ADRs written, any CONTEXT.md terms added.
+Fill `${QUALIA_TEMPLATES}/phase-context.md` with concrete content. Reference any ADRs written, any CONTEXT.md terms added.
 
 ### 7. Commit and route
 
 ```bash
 git add .planning/phase-{N}-context.md .planning/CONTEXT.md .planning/decisions/
 git commit -m "docs(phase-{N}): lock context, glossary terms, ADRs"
-node ~/.claude/bin/qualia-ui.js end "PHASE {N} CONTEXT LOCKED" "/qualia-plan {N}"
+node ${QUALIA_BIN}/qualia-ui.js end "PHASE {N} CONTEXT LOCKED" "/qualia-plan {N}"
 ```
 
 ## Rules — PHASE MODE

package/skills/qualia-doctor/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: qualia-doctor
+description: "Employee-facing framework health check. Wraps `qualia-framework doctor`, checks install targets, project state, contract coverage, planning-folder hygiene, hooks, memory, ERP queue health, and gives safe repair commands. Trigger on 'doctor', 'health check', 'framework broken', 'is Qualia installed correctly', 'Codex not picking up Qualia', 'hooks not running', 'memory broken', 'ERP queue stuck', '.planning messy'."
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+---
+
+# /qualia-doctor
+
+Diagnose whether the framework harness itself is healthy before blaming the project or the model.
+
+## 1. Install Health
+
+Run:
+
+```bash
+qualia-framework doctor
+qualia-framework trust
+```
+
+If it fails, report the failed checks first. Use safe repair commands only:
+
+```bash
+npx qualia-framework@latest install
+```
+
+Do not delete user files, configs, knowledge, or hooks manually.
+
+## 2. Project State Health
+
+Run from the project root:
+
+```bash
+node ${QUALIA_BIN}/state.js check
+```
+
+If installed under Codex only, use:
+
+```bash
+node ~/.codex/bin/state.js check
+```
+
+Classify:
+- `NO_PROJECT` -> project has not been initialized; next command is `/qualia-new` or `/qualia-map` for brownfield.
+- `schema_errors` -> recommend `node ${QUALIA_BIN}/state.js fix` or Codex equivalent.
+- `gap_cycles` at limit -> recommend replanning or escalation.
+
+## 3. Contract Health
+
+For the current phase, check whether a machine-readable contract exists:
+
+```bash
+node ${QUALIA_BIN}/state.js validate-plan --phase {N}
+```
+
+If `contract_status` is `missing`, `invalid`, or `drifted`, the harness is not at full-trust mode yet.
+
+When a contract exists, run:
+
+```bash
+node ${QUALIA_BIN}/contract-runner.js .planning/phase-{N}-contract.json
+```
+
+Use the Codex path on Codex-only installs.
+
+## 4. Planning Folder Hygiene
+
+Run:
+
+```bash
+qualia-framework planning-hygiene scan
+```
+
+If it reports loose files, show the dry-run result first. Only organize when the user approves:
+
+```bash
+qualia-framework planning-hygiene organize --write
+```
+
+Do not move files by hand; the script keeps phase-critical root files in place and moves loose reports/assets into `.planning/reports/`, `.planning/assets/`, `.planning/design/`, or `.planning/archive/loose/`.
+
+## 5. Memory Health
+
+Run:
+
+```bash
+node ${QUALIA_BIN}/knowledge.js
+node ${QUALIA_BIN}/knowledge.js list
+```
+
+Healthy memory has at least `index.md`, `agents.md`, and a writable `daily-log/` directory. Missing curated memory is not fatal, but missing installed memory files means reinstall.
+
+## 6. ERP Queue Health
+
+Run:
+
+```bash
+qualia-framework erp-flush show
+```
+
+If the queue has entries, run:
+
+```bash
+qualia-framework erp-flush drain
+```
+
+If the queue fails with `401`, the ERP API key is invalid. Use:
+
+```bash
+printf '%s' "$QUALIA_ERP_KEY" | qualia-framework set-erp-key
+```
+
+## Output
+
+End with:
+
+```text
+Harness health: PASS | DEGRADED | FAIL
+Trust score: {N}/100
+Install: ...
+State: ...
+State ledger: ...
+Contracts: ...
+Planning hygiene: ...
+Memory: ...
+Design/UI: ...
+Employee experience: ...
+ERP: ...
+Next: ...
+```
+
+## Rules
+
+1. Read diagnostics before repair.
+2. Never remove user-owned files.
+3. Treat missing contracts as degraded trust, not a project failure.
+4. Prefer reinstall for missing framework files.
+5. Prefer `state.js fix` only for malformed generated state.

package/skills/qualia-feature/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-feature
-description: "Auto-scoped single feature build. Picks inline (≤1 trivial file, no spawn) or fresh builder spawn (1-5 logic files, atomic commit) automatically from the task description. Refuses and routes to /qualia-plan for 5+ files or full phases. Flags: --force-spawn forces a builder, --force-inline forces inline. Trigger phrases: 'build this one thing', 'add a component', 'implement this feature', 'quick fix', 'small change', 'tweak', 'hot fix', 'one-line fix', 'typo', 'config tweak', 'qualia-feature'."
+description: "Auto-scoped single feature build for adding net-new capability. Picks inline (≤1 trivial file, no spawn) or fresh builder spawn (1-5 logic files, atomic commit). Refuses and routes to /qualia-plan for phase-sized work, and routes broken existing behavior to /qualia-fix. Trigger phrases: 'build this one thing', 'add a component', 'implement this feature', 'small change', 'tweak', 'one-line copy change', 'config tweak', 'qualia-feature'."
 allowed-tools:
   - Bash
   - Read
@@ -14,7 +14,7 @@ allowed-tools:
 
 # /qualia-feature — Auto-scoped Single Feature
 
-One command for everything between a typo and a phase. Auto-detects scope from the task description and picks the right execution path.
+One command for adding a small new capability outside the planned Road. Auto-detects scope from the task description and picks the right execution path.
 
 ## Usage
 
@@ -26,7 +26,7 @@ One command for everything between a typo and a phase. Auto-detects scope from t
 ## When to use
 
 - One feature outside a planned phase
-- A bug fix, typo, config tweak, or one-line change
+- A copy tweak, config tweak, or one-line non-repair change
 - A 1-5 file feature, component, API route, or integration
 - A refactor of a single module
 
@@ -34,11 +34,16 @@ One command for everything between a typo and a phase. Auto-detects scope from t
 
 - 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`
 - Optimization or polish pass → `/qualia-optimize` or `/qualia-polish`
 
 ## Process
 
+### 0. Codex goal (Codex runtime only)
+
+Per `rules/codex-goal.md` — set the thread goal with scope matching the auto-detected bucket (`quick` for inline, `feature` for spawn). Do this AFTER Step 2 (auto-detect scope) so the budget matches the actual work shape.
+
 ### 1. Capture description
 
 If invoked without args, ask: **"What do you want to build?"**
@@ -64,6 +69,7 @@ Classify the description into one of three buckets:
 - "add a", "implement", "build", "create" + a single noun (component, route, page, table, form, modal, hook, util, migration)
 - Description names a single feature with multiple touch points (e.g. "add a feedback form" → migration + API + UI = 3-4 files, but still one cohesive thing)
 - The work needs a fresh context to avoid contaminating the current conversation
+- The work repairs a non-trivial bug only if invoked explicitly with `/qualia-feature --force-spawn`; otherwise use `/qualia-fix`
 
 **Refuse signals** (any one is sufficient):
 - "build the X system", "implement the entire Y", "add complete Z support"
@@ -75,9 +81,9 @@ Classify the description into one of three buckets:
 Show the user what was detected. Always offer the escape hatch:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner feature
-node ~/.claude/bin/qualia-ui.js info "Detected scope: {inline|spawn|refuse}"
-node ~/.claude/bin/qualia-ui.js info "Reason: {one-line rationale}"
+node ${QUALIA_BIN}/qualia-ui.js banner feature
+node ${QUALIA_BIN}/qualia-ui.js info "Detected scope: {inline|spawn|refuse}"
+node ${QUALIA_BIN}/qualia-ui.js info "Reason: {one-line rationale}"
 ```
 
 Then:
@@ -110,13 +116,13 @@ git commit -m "fix: {description}"
 5. Record in state:
 
 ```bash
-node ~/.claude/bin/state.js transition --to note --notes "{brief description}" --tasks-done 1
+node ${QUALIA_BIN}/state.js transition --to note --notes "{brief description}" --tasks-done 1
 ```
 
 6. End with:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "FEATURE SHIPPED (inline)"
+node ${QUALIA_BIN}/qualia-ui.js end "FEATURE SHIPPED (inline)"
 ```
 
 ### 5. Execute the spawn path
@@ -126,9 +132,9 @@ For spawn scope:
 1. Build a quick task spec (don't write to a file, just confirm with user):
 
 ```bash
-node ~/.claude/bin/qualia-ui.js info "What: {what to build}"
-node ~/.claude/bin/qualia-ui.js info "Files: {files to create/modify, comma list}"
-node ~/.claude/bin/qualia-ui.js info "Done: {observable acceptance criteria, 1-3 bullets}"
+node ${QUALIA_BIN}/qualia-ui.js info "What: {what to build}"
+node ${QUALIA_BIN}/qualia-ui.js info "Files: {files to create/modify, comma list}"
+node ${QUALIA_BIN}/qualia-ui.js info "Done: {observable acceptance criteria, 1-3 bullets}"
 ```
 
 Ask: **"Good to build?"** Wait for confirmation.
@@ -138,7 +144,7 @@ Ask: **"Good to build?"** Wait for confirmation.
 ```
 Agent(subagent_type="qualia-builder", description="Feature: {short title}")
   prompt: |
-    Read your role: @~/.claude/agents/builder.md
+    Read your role: @${QUALIA_AGENTS}/builder.md
 
     <task>
     {task description verbatim from user}
@@ -168,17 +174,17 @@ Agent(subagent_type="qualia-builder", description="Feature: {short title}")
 4. Report:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js ok "Feature: {description}"
-node ~/.claude/bin/qualia-ui.js ok "Files: {files changed}"
-node ~/.claude/bin/qualia-ui.js ok "Commit: {commit hash}"
-node ~/.claude/bin/qualia-ui.js end "FEATURE SHIPPED (spawn)"
+node ${QUALIA_BIN}/qualia-ui.js divider
+node ${QUALIA_BIN}/qualia-ui.js ok "Feature: {description}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Files: {files changed}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Commit: {commit hash}"
+node ${QUALIA_BIN}/qualia-ui.js end "FEATURE SHIPPED (spawn)"
 ```
 
 5. Record in state:
 
 ```bash
-node ~/.claude/bin/state.js transition --to note --notes "{description}" --tasks-done 1
+node ${QUALIA_BIN}/state.js transition --to note --notes "{description}" --tasks-done 1
 ```
 
 ### 6. Execute the refuse path
@@ -186,9 +192,9 @@ node ~/.claude/bin/state.js transition --to note --notes "{description}" --tasks
 For refuse scope, do NOT build. Explain why and route:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js warn "This is too big for /qualia-feature (5+ files or multi-step workflow)."
-node ~/.claude/bin/qualia-ui.js info "Reason: {one-line — e.g. 'description names the entire auth system, not a slice'}"
-node ~/.claude/bin/qualia-ui.js end "ROUTED" "/qualia-plan"
+node ${QUALIA_BIN}/qualia-ui.js warn "This is too big for /qualia-feature (5+ files or multi-step workflow)."
+node ${QUALIA_BIN}/qualia-ui.js info "Reason: {one-line — e.g. 'description names the entire auth system, not a slice'}"
+node ${QUALIA_BIN}/qualia-ui.js end "ROUTED" "/qualia-plan"
 ```
 
 If the user is sure it's small and the classifier got it wrong, they can re-invoke with `--force-spawn`.