qualia-framework 6.2.9 → 6.3.0

package/rules/speed.md

@@ -50,5 +50,4 @@ When a Qualia command exists for the situation, use it — don't reinvent:
 - `/qualia-feature` — single feature, auto-scoped: inline for trivia, fresh builder spawn for 1-5 file features
 - `/qualia-ship` — full deploy pipeline (quality gates → commit → deploy → verify)
 - `/qualia-review` — production audit
-- `/qualia-pause` — save context before clearing the conversation
 - `/qualia-learn` — save a lesson from a mistake

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
@@ -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:
@@ -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, 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 | → 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?"
@@ -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}"
 ```

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,7 +34,8 @@ 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`
-- Investigating a symptom you can't name yet → `/qualia-debug`
+- Broken existing behavior, regression, failing test, or hotfix → `/qualia-fix`
+- Investigating a symptom you can't name yet → `/qualia-review`
 - Optimization or polish pass → `/qualia-optimize` or `/qualia-polish`
 
 ## Process
@@ -68,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"
@@ -79,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:
@@ -114,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
@@ -130,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.
@@ -142,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}
@@ -172,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
@@ -190,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`.