qualia-framework 6.2.9 → 6.3.0

package/skills/qualia-test/SKILL.md

@@ -25,7 +25,7 @@ Generate tests for client project code. Detect framework, classify targets, writ
 ## Process
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner test
+node ${QUALIA_BIN}/qualia-ui.js banner test
 ```
 
 ### 1. Detect Test Framework
@@ -118,10 +118,10 @@ npx vitest run --coverage 2>&1 | tail -30
 ### 5. Report
 
 ```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js info "Files tested: {N}"
-node ~/.claude/bin/qualia-ui.js ok "Passing: {pass}/{total}"
-node ~/.claude/bin/qualia-ui.js end "TESTS DONE"
+node ${QUALIA_BIN}/qualia-ui.js divider
+node ${QUALIA_BIN}/qualia-ui.js info "Files tested: {N}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Passing: {pass}/{total}"
+node ${QUALIA_BIN}/qualia-ui.js end "TESTS DONE"
 ```
 
 If any tests fail, show the failures and offer to fix them.

package/skills/qualia-verify/SKILL.md

@@ -28,30 +28,44 @@ Spawn verifier to check phase goal. Does NOT trust build summaries; greps codeba
 ```bash
 echo "---PLAN---"
 cat .planning/phase-{N}-plan.md 2>/dev/null
+echo "---CONTRACT---"
+cat .planning/phase-{N}-contract.json 2>/dev/null || echo "NO_JSON_CONTRACT"
 echo "---PREVIOUS---"
 cat .planning/phase-{N}-verification.md 2>/dev/null || echo "NONE"
 ```
 
-### 2. Spawn Verifier (Fresh Context)
+### 2. Run Machine Contract First
+
+If `.planning/phase-{N}-contract.json` exists, run:
+
+```bash
+node ${QUALIA_BIN}/contract-runner.js .planning/phase-{N}-contract.json
+```
+
+If it fails, the phase cannot PASS. Still spawn the verifier to explain the failure and identify the smallest gap-closure tasks. If it passes, pass the evidence file into the verifier prompt.
+
+### 3. Spawn Verifier (Fresh Context)
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner verify {N} "{phase name}"
-node ~/.claude/bin/qualia-ui.js spawn verifier "Goal-backward check..."
+node ${QUALIA_BIN}/qualia-ui.js banner verify {N} "{phase name}"
+node ${QUALIA_BIN}/qualia-ui.js spawn verifier "Goal-backward check..."
 ```
 
 ```
 Agent(prompt="
-Role: @~/.claude/agents/verifier.md
+Role: @${QUALIA_AGENTS}/verifier.md
 
 Project: @.planning/PROJECT.md
 Plan + AC + validation: @.planning/phase-{N}-plan.md
+Machine contract: @.planning/phase-{N}-contract.json
+Contract evidence: @.planning/evidence/phase-{N}-contract-run.json
 {Re-verify → previous gaps: @.planning/phase-{N}-verification.md}
 
 Verify phase. Every finding needs file:line evidence. Severity Rubric for all labels. Output: .planning/phase-{N}-verification.md
 ", subagent_type="qualia-verifier", description="Verify phase {N}")
 ```
 
-### 2b. Browser QA (if phase touched frontend)
+### 3b. Browser QA (if phase touched frontend)
 
 If plan Files include `.tsx`/`.jsx`/`.css`/`.scss` or `app/`/`pages/`/`components/` paths, spawn browser QA parallel:
 
@@ -64,7 +78,7 @@ If frontend:
 
 ```
 Agent(prompt="
-Role: @~/.claude/agents/qa-browser.md
+Role: @${QUALIA_AGENTS}/qa-browser.md
 
 Plan: @.planning/phase-{N}-plan.md
 Verification: @.planning/phase-{N}-verification.md
@@ -75,17 +89,17 @@ Drive dev server, test routes phase touched. Append '## Browser QA' to verificat
 
 Wait for both verifier + QA before step 3. Playwright MCP unavailable → QA returns BLOCKED (note, not phase failure).
 
-### 2c. Adversarial Second Opinion (--adversarial flag, optional)
+### 3c. Adversarial Second Opinion (--adversarial flag, optional)
 
 `--adversarial` in args, OR milestone is `Handoff`, OR plan touches `auth|payment|migration|rls|service_role` → spawn SECOND verifier in fresh context. Mitigates self-grading bias (~70% fewer findings without adversarial pass).
 
 ```bash
-node ~/.claude/bin/qualia-ui.js spawn verifier "Adversarial pass — find what's wrong"
+node ${QUALIA_BIN}/qualia-ui.js spawn verifier "Adversarial pass — find what's wrong"
 ```
 
 ```
 Agent(prompt="
-Role: @~/.claude/agents/verifier.md
+Role: @${QUALIA_AGENTS}/verifier.md
 
 ADVERSARIAL reviewer. Find what's WRONG. Assume cooperative verifier missed something. Same Severity Rubric + evidence-citation req. Bias toward edge cases:
   - Untested error paths?
@@ -104,14 +118,14 @@ Append '## Adversarial Findings' to verification file. Empty section fine if not
 
 Findings merge into main report. Union PASS/FAIL: either pass found CRITICAL/HIGH → phase FAIL.
 
-### 2d. INSUFFICIENT EVIDENCE downgrade (mandatory)
+### 3d. INSUFFICIENT EVIDENCE downgrade (mandatory)
 
 The verifier marks criteria it could not check (budget exhaustion, missing context) as `INSUFFICIENT EVIDENCE`. The orchestrator must treat those as FAIL before declaring PASS. Grep the verification file and downgrade immediately:
 
 ```bash
 IE_COUNT=$(grep -c "INSUFFICIENT EVIDENCE" .planning/phase-{N}-verification.md 2>/dev/null || echo 0)
 if [ "$IE_COUNT" -gt 0 ]; then
-  node ~/.claude/bin/qualia-ui.js warn "${IE_COUNT} criteria marked INSUFFICIENT EVIDENCE — downgrading verdict to FAIL"
+  node ${QUALIA_BIN}/qualia-ui.js warn "${IE_COUNT} criteria marked INSUFFICIENT EVIDENCE — downgrading verdict to FAIL"
   # Rewrite the verdict line in-place
   sed -i 's/^result: PASS$/result: FAIL/' .planning/phase-{N}-verification.md
   sed -i 's/^## Verdict$/## Verdict\n\n**Downgraded to FAIL:** '"${IE_COUNT}"' criteria left unchecked. Re-run with larger budget (`max(25, tasks*5)` already applied) or simplify the phase plan./' .planning/phase-{N}-verification.md
@@ -126,20 +140,20 @@ Read verification report. Present:
 
 **PASS:**
 ```bash
-node ~/.claude/bin/qualia-ui.js ok "All {count} criteria passed"
-node ~/.claude/bin/qualia-ui.js end "PHASE {N} VERIFIED" "/qualia-plan {N+1}"
+node ${QUALIA_BIN}/qualia-ui.js ok "All {count} criteria passed"
+node ${QUALIA_BIN}/qualia-ui.js end "PHASE {N} VERIFIED" "/qualia-plan {N+1}"
 ```
 (Last phase → `/qualia-polish` as next command.)
 
 **FAIL:**
 ```bash
-node ~/.claude/bin/qualia-ui.js ok "Passed: {pass_count}"
-node ~/.claude/bin/qualia-ui.js fail "Failed: {fail_count}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Passed: {pass_count}"
+node ${QUALIA_BIN}/qualia-ui.js fail "Failed: {fail_count}"
 ```
 
 Per gap:
 ```bash
-node ~/.claude/bin/qualia-ui.js fail "{gap description}"
+node ${QUALIA_BIN}/qualia-ui.js fail "{gap description}"
 ```
 
 **Self-healing:** before re-planning gaps, run postmortem so the framework learns from the miss. Writes `.planning/phase-{N}-postmortem.md`. Does NOT auto-apply deltas unless user runs `/qualia-postmortem --apply`.
@@ -150,13 +164,21 @@ node ~/.claude/bin/qualia-ui.js fail "{gap description}"
 
 End:
 ```bash
-node ~/.claude/bin/qualia-ui.js end "PHASE {N} GAPS FOUND" "/qualia-plan {N} --gaps"
+node ${QUALIA_BIN}/qualia-ui.js end "PHASE {N} GAPS FOUND" "/qualia-plan {N} --gaps"
 ```
 
 ### 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 ~/.claude/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.
@@ -166,7 +188,7 @@ Do NOT edit STATE.md or tracking.json manually; state.js handles both.
 Capture new state for auto-chain routing:
 
 ```bash
-NEW_STATE=$(node ~/.claude/bin/state.js check)
+NEW_STATE=$(node ${QUALIA_BIN}/state.js check)
 # Parse: .phase, .total_phases, .status, .verification
 # Read .planning/JOURNEY.md to check if last phase of milestone
 ```
@@ -189,8 +211,8 @@ Handoff: milestone name == "Handoff" AND last phase.
 **Halt (gap cycle limit):**
 
 ```bash
-node ~/.claude/bin/qualia-ui.js fail "Phase {N} failed verification {cycles} times -- gap limit reached"
-node ~/.claude/bin/qualia-ui.js warn "Human intervention required. Options:"
+node ${QUALIA_BIN}/qualia-ui.js fail "Phase {N} failed verification {cycles} times -- gap limit reached"
+node ${QUALIA_BIN}/qualia-ui.js warn "Human intervention required. Options:"
 echo "  1. Re-plan from scratch: /qualia-plan {N}"
 echo "  2. Adjust roadmap (scope wrong)"
 echo "  3. Escalate to Fawzi (EMPLOYEE role)"
@@ -200,9 +222,9 @@ echo "  3. Escalate to Fawzi (EMPLOYEE role)"
 
 ```bash
 # PASS (or "/qualia-milestone" if last phase, "/qualia-polish" if overall last)
-node ~/.claude/bin/qualia-ui.js end "PHASE {N} VERIFIED" "/qualia-plan {N+1}"
+node ${QUALIA_BIN}/qualia-ui.js end "PHASE {N} VERIFIED" "/qualia-plan {N+1}"
 # FAIL
-node ~/.claude/bin/qualia-ui.js end "PHASE {N} GAPS FOUND" "/qualia-plan {N} --gaps"
+node ${QUALIA_BIN}/qualia-ui.js end "PHASE {N} GAPS FOUND" "/qualia-plan {N} --gaps"
 ```
 
 ### 5. Passive Knowledge Capture (on FAIL)

package/skills/zoho-workflow/SKILL.md

@@ -43,7 +43,7 @@ The full handoff runbook lives in the qualia-erp repo: `docs/finance-runbook.md`
 ## Email Formatting Rules (MANDATORY)
 
 - Always append Fawzi's signature at the bottom of every email
-- Read signature HTML from `~/.claude/knowledge/email-signature.html`
+- Read signature HTML from `${QUALIA_KNOWLEDGE}/email-signature.html`
 - Never use dashes (---) or horizontal separators
 - Never use emojis
 - Professional, direct tone

package/templates/help.html

@@ -297,7 +297,7 @@
   <div class="header-content">
     <h1><span>Qualia</span> Framework</h1>
     <p>Plan, build, verify, ship. The AI-powered workflow for Qualia Solutions.</p>
-    <div class="version">{{VERSION}} &middot; 33 skills</div>
+    <div class="version">{{VERSION}} &middot; 35 skills</div>
   </div>
 </div>
 
@@ -328,7 +328,7 @@
 
   <!-- Skills -->
   <section>
-    <h2>Skills (28)</h2>
+    <h2>Skills</h2>
 
     <!-- Road (core flow) -->
     <div class="cmd-group">
@@ -360,15 +360,13 @@
     <!-- Quality -->
     <div class="cmd-group">
       <h3>Quality</h3>
-      <p class="cmd-group-note">Diagnose, audit, optimize, polish, test.</p>
+      <p class="cmd-group-note">Fix, diagnose, audit, optimize, polish, test.</p>
       <div class="commands">
-        <div class="cmd"><span class="cmd-name">/qualia-debug</span><span class="cmd-desc">Structured debugging &mdash; symptom gathering, diagnosis confirmation, root cause analysis. Trigger on 'debug', 'find bug', 'fix error', 'something is broken'.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-review</span><span class="cmd-desc">Production audit with scored diagnostics. Runs real commands, scores findings by severity. Trigger on 'review', 'audit', 'code review', 'security check'.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-optimize</span><span class="cmd-desc">Deep optimization pass &mdash; reads .planning/ AND codebase to find performance, design, UI, backend, and frontend issues. Spawns parallel specialist agents. Supports --perf, --ui, --backend, --alignment, --fix flags.</span></div>
+        <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-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>
 
@@ -377,9 +375,9 @@
       <h3>Quick Paths</h3>
       <p class="cmd-group-note">Lightweight alternatives when the full road is overkill.</p>
       <div class="commands">
-        <div class="cmd"><span class="cmd-name">/qualia-feature</span><span class="cmd-desc">Auto-scoped single-feature build. Inline for trivia (typo, config), fresh builder spawn for 1-5 file features. Refuses and routes to /qualia-plan for phase-sized work. Flags: --force-spawn, --force-inline.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-polish</span><span class="cmd-desc">Design pass, scope-adaptive &mdash; component, route, full app, redesign, critique, quick. Add --loop for the autonomous screenshot &rarr; score &rarr; fix loop.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-vibe</span><span class="cmd-desc">Fast aesthetic pivot (~3 min) &mdash; swap design tokens (color, type, depth, motion), keep layout untouched. Default proposes ONE direction. Modes: --variants for A/B/C, --extract URL to reverse-engineer DESIGN.md from a reference site, --sync for code &harr; DESIGN.md back-sync.</span></div>
+        <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-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>
 
@@ -389,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>
@@ -399,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>
 
@@ -410,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>
@@ -421,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>
@@ -548,7 +539,7 @@
 <div class="footer">
   <strong>Welcome to the future with Qualia.</strong><br>
   Qualia Solutions &mdash; Nicosia, Cyprus
-  <span class="footer-version">qualia-framework {{VERSION}} &middot; 33 skills</span>
+  <span class="footer-version">qualia-framework {{VERSION}} &middot; 35 skills</span>
 </div>
 
 </body>