qualia-framework 4.0.0 → 4.0.3

package/rules/frontend.md

@@ -109,18 +109,10 @@ These are Qualia brand standards — mandatory for every frontend component. Not
 If `.planning/DESIGN.md` exists in the project, it takes precedence over these defaults.
 Read it before any frontend work. It contains project-specific: palette, typography, spacing, component patterns.
 
-## Impeccable Design Skills (global)
-- `/polish` — Final detail pass before shipping
-- `/bolder` — Amplify safe/boring designs
-- `/design-quieter` — Tone down overly aggressive designs
-- `/animate` — Add purposeful micro-interactions
-- `/colorize` — Inject strategic color into monochrome UIs
-- `/clarify` — Fix unclear UX copy, labels, error messages
-- `/critique` — Design director-level review
-- `/distill` — Strip unnecessary complexity
-- `/delight` — Add memorable touches and personality
-- `/harden` — Edge cases, overflow, i18n robustness
-- `/responsive` — Cross-device responsive adaptation
+## Qualia design commands
+- `/qualia-design` — One-shot design transformation (critique + fix + polish + responsive + harden)
+- `/qualia-polish` — Final detail pass before shipping (run after all phases verified)
+- `/qualia-review` — Scored production audit
 
 ### Recommended workflow
-1. Build feature → 2. `/critique` → 3. `/polish` → 4. `/harden` → ship
+1. Build feature → 2. `/qualia-design` → 3. `/qualia-polish` → ship

package/skills/qualia/SKILL.md

@@ -1,6 +1,11 @@
 ---
 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."
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
 ---
 
 # /qualia — What's Next?

package/skills/qualia-build/SKILL.md

@@ -1,6 +1,16 @@
 ---
 name: qualia-build
 description: "Execute the current phase — spawns builder subagents per task with wave-based parallelization. Fresh context per task."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+  - TaskCreate
+  - TaskUpdate
 ---
 
 # /qualia-build — Build a Phase

package/skills/qualia-debug/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: qualia-debug
 description: "Structured debugging — symptom gathering, diagnosis confirmation, root cause analysis. Trigger on 'debug', 'find bug', 'fix error', 'something is broken', 'not working', 'weird behavior', 'layout broken', 'CSS issue', 'slow page', 'performance'."
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-debug — Structured Debugging

package/skills/qualia-design/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: qualia-design
 description: "One-shot design transformation — critiques, fixes, polishes, hardens, makes responsive. No reports, no choices, just makes it professional. Trigger on 'fix the design', 'make it look better', 'redesign', 'design pass', 'make it modern', 'it looks ugly', 'fix the UI'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-design — One-Shot Design Transformation
@@ -87,7 +95,7 @@ git commit -m "style: design transformation"
   - {key change 2}
   - {key change 3}
 
-  Fine-tune: /bolder, /design-quieter, /colorize, /animate
+  Next: /qualia-polish (final pass) · /qualia-review (scored audit)
 ```
 
 ## Rules

package/skills/qualia-discuss/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: qualia-discuss
 description: "Capture phase decisions, trade-offs, and constraints BEFORE planning. Use for complex phases with regulatory, compliance, or architectural stakes. Creates .planning/phase-{N}-context.md that planner honors as locked input."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - AskUserQuestion
 ---
 
 # /qualia-discuss — Phase Context Capture

package/skills/qualia-handoff/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: qualia-handoff
 description: "Client delivery — produces the 4 mandatory Handoff deliverables (production URL, documentation, client assets archive, ERP finalization). Triggered at the end of the Handoff milestone."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
 ---
 
 # /qualia-handoff — Client Delivery

package/skills/qualia-help/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: qualia-help
 description: "Open the Qualia Framework reference guide in the browser. A beautiful themed HTML page with all commands, rules, services, and the road. Trigger on 'help', 'how does this work', 'show me the commands', 'qualia help', 'reference'."
+allowed-tools:
+  - Bash
+  - Read
 ---
 
 # /qualia-help — Framework Reference
@@ -12,14 +15,25 @@ Opens a Qualia-themed HTML reference guide in your default browser.
 ### 1. Generate the HTML
 
 ```bash
-# Read the template and inject the current version
-VERSION=$(node -e "console.log(require(require('os').homedir() + '/.claude/.qualia-config.json').version || 'v3')" 2>/dev/null || echo "v3")
+# Read the template and inject the current version.
+# Prefer .qualia-config.json; fall back to the framework package.json; last resort is the
+# literal string "latest" so the UI never lies about a specific version.
+VERSION=$(node -e "
+  const fs = require('fs'), path = require('path'), os = require('os');
+  const cfg = path.join(os.homedir(), '.claude', '.qualia-config.json');
+  const pkg = path.join(os.homedir(), '.claude', 'qualia-framework', 'package.json');
+  try { const v = JSON.parse(fs.readFileSync(cfg,'utf8')).version; if (v) { console.log(v); process.exit(0); } } catch {}
+  try { const v = JSON.parse(fs.readFileSync(pkg,'utf8')).version; if (v) { console.log('v'+v); process.exit(0); } } catch {}
+  console.log('latest');
+" 2>/dev/null || echo "latest")
 TEMPLATE="$HOME/.claude/qualia-templates/help.html"
 OUTPUT="/tmp/qualia-help.html"
 
-# If template doesn't exist, check the framework install
+# If template doesn't exist in the user home, check the installed framework copy.
 if [ ! -f "$TEMPLATE" ]; then
-  TEMPLATE="$(dirname "$(dirname "$(which qualia-framework 2>/dev/null || echo '')")")/templates/help.html"
+  for CANDIDATE in "$HOME/.claude/qualia-framework/templates/help.html"; do
+    if [ -f "$CANDIDATE" ]; then TEMPLATE="$CANDIDATE"; break; fi
+  done
 fi
 ```
 

package/skills/qualia-idk/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: qualia-idk
 description: "Diagnostic intelligence for 'I don't know what's going on.' Runs two isolated scans (.planning/ vs codebase), cross-references against the user's confusion, then explains the situation in plain language with a concrete recommended next step. Use whenever the user says 'I don't know', 'something feels off', 'not sure what to do', 'am I doing this right', 'what's happening', 'help me understand'."
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-idk — "I Don't Know What's Going On"

package/skills/qualia-learn/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: qualia-learn
 description: "Save a learning, pattern, fix, or client preference to the knowledge base. Persists across projects and sessions. Trigger on 'remember this', 'save this pattern', 'learned something', 'note for future', 'client prefers', 'qualia-learn'."
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
 ---
 
 # /qualia-learn — Save Knowledge

package/skills/qualia-map/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: qualia-map
 description: "Map an existing codebase to infer architecture, stack, conventions, and what's already built. For brownfield projects — run BEFORE /qualia-new so Validated requirements get inferred from existing code."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-map — Codebase Mapping (Brownfield)

package/skills/qualia-milestone/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: qualia-milestone
 description: "Close the current milestone and open the next one — loads the next milestone's scope from JOURNEY.md (no ad-hoc naming). Archives artifacts, marks requirements Complete, regenerates ROADMAP.md for the next milestone."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Agent
 ---
 
 # /qualia-milestone — Milestone Closeout

package/skills/qualia-new/SKILL.md

@@ -1,6 +1,18 @@
 ---
 name: qualia-new
 description: "Set up a new project from scratch — deep questioning, ALWAYS-AUTO research, JOURNEY.md with all milestones to handoff, single approval gate, optional auto-chain into building. Use when starting any new client project."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+  - AskUserQuestion
+  - TaskCreate
+  - TaskUpdate
+  - TaskList
 ---
 
 # /qualia-new — New Project (Full Journey)
@@ -204,7 +216,7 @@ Display top 3 from SUMMARY.md (stack recommendation, table stakes, top pitfall).
 
 ### Step 9. Feature Scoping (Multi-Milestone)
 
-Read `.planning/research/FEATURES.md` and present the feature landscape. Unlike v3, features are scoped **to milestones**, not just to v1/v2.
+Read `.planning/research/FEATURES.md` and present the feature landscape. Features are scoped **to milestones** — you'll decide per-feature which milestone owns it.
 
 For each category, use AskUserQuestion:
 

package/skills/qualia-optimize/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: qualia-optimize
 description: "Deep optimization pass — reads .planning/ AND codebase to find performance, design, UI, backend, and frontend issues. Spawns parallel specialist agents. Use this skill whenever the user says 'optimize', 'optimization pass', 'find issues', 'qualia-optimize', 'deep optimize', 'performance audit', 'design alignment check', 'speed up', 'slow', 'bundle size', or wants a comprehensive quality sweep. Supports --perf, --ui, --backend, --alignment, --fix flags."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # Qualia Optimize — Deep Codebase + Planning Optimization

package/skills/qualia-pause/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: qualia-pause
 description: "Save session context for seamless handoff. Creates .continue-here.md so the next session picks up exactly where you left off. Trigger on 'pause', 'stop for now', 'save progress', 'continue later', 'pick up tomorrow'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
 ---
 
 # /qualia-pause — Session Handoff

package/skills/qualia-plan/SKILL.md

@@ -1,6 +1,16 @@
 ---
 name: qualia-plan
 description: "Plan the current phase — spawns planner, validates with plan-checker in a revision loop (max 3), optionally runs discuss/research first. Use when ready to plan a phase."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+  - TaskCreate
+  - TaskUpdate
 ---
 
 # /qualia-plan — Plan a Phase
@@ -196,7 +206,7 @@ When invoked as `/qualia-plan {N} --gaps`, the planner is in gap-closure mode:
 2. For each FAIL item, create a targeted fix task:
    - **Files:** specific files that failed verification
    - **Action:** specific fix (not "fix auth" — "add session persistence check in src/lib/auth.ts signIn function")
-   - **Done when:** the exact verification criterion that previously failed, restated
+   - **Acceptance Criteria:** the exact verification criterion that previously failed, restated as an observable behavior
 3. Do NOT re-plan passing items. Do NOT add new features. Gap plans are surgical.
 4. Write to `.planning/phase-{N}-gaps-plan.md` (separate from original plan)
 5. All gap tasks are Wave 1 (parallel) unless they share files

package/skills/qualia-polish/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: qualia-polish
 description: "Design and UX pass — anti-AI-slop, genuine craft, responsive, accessible. Run after all phases are verified."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-polish — Design Pass

package/skills/qualia-quick/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: qualia-quick
 description: "Fast path for small tasks — bug fixes, tweaks, hot fixes. Skips full phase planning. Trigger on 'quick fix', 'small change', 'tweak', 'hot fix', 'one-line fix', 'quick edit', 'small bug'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
 ---
 
 # /qualia-quick — Quick Task

package/skills/qualia-report/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: qualia-report
 description: "Generate session report and commit to repo. Mandatory before clock-out."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
 ---
 
 # /qualia-report — Session Report

package/skills/qualia-research/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: qualia-research
 description: "Deep-research a niche domain or library BEFORE planning a specific phase. Spawns the researcher agent with Context7/WebFetch access. Writes to .planning/phase-{N}-research.md."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Agent
+  - WebFetch
+  - WebSearch
 ---
 
 # /qualia-research — Per-Phase Deep Research

package/skills/qualia-resume/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: qualia-resume
 description: "Restore context from a previous session. Reads .continue-here.md or STATE.md, summarizes where you left off, routes to next action. Trigger on 'resume', 'continue', 'pick up where I left off', 'what was I doing'."
+allowed-tools:
+  - Bash
+  - Read
 ---
 
 # /qualia-resume — Resume Work

package/skills/qualia-review/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: qualia-review
 description: "Production audit with scored diagnostics. Runs real commands, scores findings by severity. Trigger on 'review', 'audit', 'code review', 'security check', 'production check'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-review — Production Audit

package/skills/qualia-ship/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: qualia-ship
 description: "Deploy to production — quality gates, commit, push, deploy, verify. Use when ready to go live."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
 ---
 
 # /qualia-ship — Deploy

package/skills/qualia-skill-new/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: qualia-skill-new
 description: "Author a new Qualia skill or agent. Use when the user says 'create a new skill', 'add a skill', 'I want to build a skill', 'make this a reusable command', 'turn this into a skill'. Generates the SKILL.md, registers it in the right location, and optionally ships to the framework repo."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - AskUserQuestion
 ---
 
 # /qualia-skill-new — Author a New Skill

package/skills/qualia-task/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: qualia-task
 description: "Build a single task — more structured than /qualia-quick, lighter than /qualia-build. Spawns a fresh builder agent for one focused task."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Agent
+  - AskUserQuestion
 ---
 
 # /qualia-task — Single Task Builder
@@ -61,7 +68,7 @@ Agent(subagent_type: "qualia-builder")
 
 Task: {task description}
 Files: {files to create/modify}
-Done when: {completion criteria}
+Acceptance Criteria: {observable completion criteria, 1-3 bullet points}
 
 Context: Read PROJECT.md if it exists. Follow all rules (security, frontend, deployment).
 ```

package/skills/qualia-test/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: qualia-test
 description: "Generate or run tests for client projects. Trigger on 'write tests', 'add tests', 'test this', 'run tests', 'test coverage', 'need tests for'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
 ---
 
 # /qualia-test — Test Generator

package/skills/qualia-verify/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: qualia-verify
 description: "Goal-backward verification — checks if the phase ACTUALLY works, not just if tasks completed. Spawns verifier agent."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-verify — Verify a Phase

package/templates/help.html

@@ -291,13 +291,13 @@
 </head>
 <body>
 
-<div class="version-pill">v3.6.0</div>
+<div class="version-pill">{{VERSION}}</div>
 
 <div class="header">
   <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">v3.6.0 &middot; 26 skills</div>
+    <div class="version">{{VERSION}} &middot; 26 skills</div>
   </div>
 </div>
 
@@ -430,7 +430,7 @@
         <div class="cmd"><span class="cmd-name">qualia-framework install</span><span class="cmd-desc">Install or reinstall the framework.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework update</span><span class="cmd-desc">Update to the latest version.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework version</span><span class="cmd-desc">Show installed version + check for updates.</span></div>
-        <div class="cmd"><span class="cmd-name">qualia-framework migrate</span><span class="cmd-desc">Upgrade v2 settings to v3.</span></div>
+        <div class="cmd"><span class="cmd-name">qualia-framework migrate</span><span class="cmd-desc">Upgrade legacy settings.json to the current hook layout.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework analytics</span><span class="cmd-desc">Hook telemetry, verification pass rates, gap cycles.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework team</span><span class="cmd-desc">List, add, or remove team members.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework traces</span><span class="cmd-desc">View recent hook activity.</span></div>
@@ -536,7 +536,7 @@
 <div class="footer">
   <strong>Welcome to the future with Qualia.</strong><br>
   Qualia Solutions &mdash; Nicosia, Cyprus
-  <span class="footer-version">qualia-framework v3.6.0 &middot; 26 skills</span>
+  <span class="footer-version">qualia-framework {{VERSION}} &middot; 26 skills</span>
 </div>
 
 </body>

package/tests/hooks.test.sh

@@ -218,25 +218,25 @@ export default function P(){return null}
 EOF
 OUT=$(cd "$TMP" && $NODE "$HOOKS_DIR/pre-deploy-gate.js" 2>&1)
 RC=$?
-if [ "$RC" -eq 1 ] \
+if [ "$RC" -eq 2 ] \
    && echo "$OUT" | grep -q "BLOCKED" \
    && echo "$OUT" | grep -q "service_role"; then
-  echo "  ✓ service_role leak in app/ → blocked with diagnostic"
+  echo "  ✓ service_role leak in app/ → blocked with diagnostic (exit 2)"
   PASS=$((PASS + 1))
 else
-  echo "  ✗ service_role leak in app/ → blocked (exit=$RC)"
+  echo "  ✗ service_role leak in app/ → blocked (exit=$RC, expected 2)"
   FAIL=$((FAIL + 1))
 fi
 rm -rf "$TMP"
 
-# service_role leak in components/ → BLOCKED
+# service_role leak in components/ → BLOCKED (exit 2 per PreToolUse contract)
 TMP=$(mktemp -d)
 mkdir -p "$TMP/components"
 cat > "$TMP/components/Widget.tsx" <<'EOF'
 const key = "service_role_literal_leak";
 EOF
 (cd "$TMP" && $NODE "$HOOKS_DIR/pre-deploy-gate.js" >/dev/null 2>&1)
-assert_exit "service_role in components/ → blocked" 1 $?
+assert_exit "service_role in components/ → blocked (exit 2)" 2 $?
 rm -rf "$TMP"
 
 # service_role in a *.server.ts file → allowed (skip convention)