qualia-framework 6.3.0 → 6.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "description": "Claude Code and Codex workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"

package/skills/qualia/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia
-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'."
+description: "Mechanical state-driven router — reads state.js, returns the exact next command. Cheap and instant. Triggers: '/qualia', 'what next', 'what now'. For deeper situational confusion use /qualia-idk."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-build
-description: "Executes a planned phase by spawning fresh builder subagents per task with wave-based parallelization. Each task gets isolated context, commits atomically, and runs its own validation. Use when the user says 'build this phase', 'execute the plan', 'start building', 'run the build', 'qualia-build', or after /qualia-plan approves a phase plan."
+description: "Execute a planned phase — fresh builder subagents per task, wave-based parallelization, atomic commits, per-task validation. Triggers: 'build this phase', 'execute the plan', 'start building', 'qualia-build'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-discuss/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-discuss
-description: "Alignment interview. Two modes. PROJECT MODE (default, no args) is the non-technical kickoff before /qualia-new — 8 questions for demo projects, 14 for full projects, output is .planning/project-discovery.md. PHASE MODE (with N arg, e.g. /qualia-discuss 2) is the technical aggressive grilling before /qualia-plan N — one question at a time with recommended answer, output is .planning/phase-{N}-context.md. Trigger phrases: 'discuss', 'kickoff interview', 'grill me', 'stress test this plan', 'wait let's think about this one', 'I'm not sure how to approach this'."
+description: "Alignment interview — PROJECT MODE before /qualia-new, PHASE MODE before /qualia-plan N. Triggers: 'discuss', 'kickoff interview', 'grill me', 'stress test this plan', 'I'm not sure how to approach this'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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'."
+description: "Framework health check — install, project state, contracts, hooks, memory, ERP queue. Suggests safe repair commands. Triggers: 'doctor', 'health check', 'framework broken', 'hooks not running', 'ERP queue stuck'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-feature/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 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'."
+description: "Auto-scoped single-feature build (inline for trivia, fresh spawn for 1-5 files). Routes phase-sized work to /qualia-plan, broken behavior to /qualia-fix. Triggers: 'build this one thing', 'add a component', 'implement this feature', 'small change', 'tweak'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-fix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-fix
-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'."
+description: "Practical repair lane for broken behavior — root-cause investigation + /qualia-feature execution. Triggers: 'fix this', 'bug', 'broken', 'error', 'failing test', 'regression', 'hotfix', 'layout broken', 'slow page'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-idk/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: qualia-idk
+description: "Deep diagnostic for 'I don't know what's going on.' Reads conversation context + the planning folder + the codebase in three isolated scans, cross-references against the user's confusion, then returns plain-language guidance PLUS a paste-ready Qualia command sequence to unstick them. 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', 'where am I', 'lost'."
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+  - Agent
+---
+
+# /qualia-idk — "I Don't Know What's Going On"
+
+Not a router. A **diagnostician**. Use when the user isn't stuck on a single command — they're stuck on **understanding the situation**. Returns guidance + a Qualia command sequence the user can paste.
+
+## How This Differs from `/qualia`
+
+| `/qualia` | `/qualia-idk` |
+|---|---|
+| Mechanical: reads state.js, returns one `/qualia-X` | Interpretive: reads conversation + planning + code |
+| "What's my next command?" | "What is happening, and what sequence gets me unstuck?" |
+| Always returns a skill name | Returns plain-language guidance + a multi-command sequence |
+| Cheap, instant (~2s) | Three parallel scans, ~30–45s |
+
+Run `/qualia` when the user knows what they're trying to do. Run `/qualia-idk` when the user's confusion is about **the situation itself** — scope, drift, or where to even begin.
+
+## Process
+
+### Step 0. Banner
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js banner router
+node ${QUALIA_BIN}/qualia-ui.js spawn "diagnostic" "Reading conversation, planning, and codebase in isolation..."
+```
+
+Say: **"Let me take a proper look."**
+
+### Step 1. Capture the User's Confusion
+
+Look at the recent conversation. Note:
+- What did the user just say or ask?
+- Any recent errors, failed commands, surprising output?
+- Any mismatch between what they expected and what happened?
+- Sentiment cues: "lost", "stuck", "weird", "broken", "where am I" — record verbatim.
+
+If conversation context is thin, ask:
+- header: "What's unclear?"
+- question: "Where are you stuck? (one sentence is fine)"
+- Free text.
+
+Store as `<user_confusion>`.
+
+### Step 2. Capture Session Context (local, fast)
+
+Before spawning scans, gather cheap session signals:
+
+```bash
+# Where is the user right now?
+test -f .continue-here.md && head -30 .continue-here.md
+test -f .planning/STATE.md && head -20 .planning/STATE.md
+git log --oneline -5 2>/dev/null
+git status --short 2>/dev/null | head -10
+
+# Recent planning artifacts (mtime tells us what was last touched)
+ls -lt .planning/phase-*-*.md 2>/dev/null | head -8
+ls -lt .planning/decisions/*.md 2>/dev/null | head -5
+
+# Is there a halt / FAIL we should know about?
+grep -l "FAIL\|INSUFFICIENT EVIDENCE\|HALT" .planning/phase-*-verification.md 2>/dev/null
+```
+
+Store as `<session_context>`.
+
+### Step 3. Spawn Three Isolated Scans (Parallel)
+
+Three fresh subagents. Each sees ONLY its scope — no cross-contamination. They run in parallel; wait for all three.
+
+**Agent A — Planning View** (broader than v1: now reads CONTEXT, REQUIREMENTS, decisions/, all phase artifacts, not just the latest):
+
+```
+Agent(prompt="
+You are a read-only diagnostic scanner for the .planning/ folder only.
+
+Read ALL of the following if present:
+  - .planning/PROJECT.md
+  - .planning/CONTEXT.md (domain glossary)
+  - .planning/JOURNEY.md
+  - .planning/REQUIREMENTS.md
+  - .planning/ROADMAP.md
+  - .planning/STATE.md
+  - .planning/tracking.json
+  - .planning/phase-*-plan.md (ALL, not just latest)
+  - .planning/phase-*-verification.md (ALL — flag any FAILs)
+  - .planning/phase-*-context.md (from /qualia-discuss PHASE MODE, if any)
+  - .planning/phase-*-research.md (if any)
+  - .planning/DESIGN.md (skim)
+  - .planning/decisions/*.md (ADRs — short read)
+  - .continue-here.md (if present)
+
+DO NOT read any source code — no src/, app/, components/, lib/, etc.
+DO NOT run any build tools.
+
+Produce a 'Plan View' report answering:
+  1. What is this project? (one sentence from PROJECT.md)
+  2. Where does the plan say we ARE? (current milestone N of M + phase P of Q + status)
+  3. What SHOULD be true right now? (current phase's acceptance criteria)
+  4. What's UNFINISHED? (upcoming phases / unresolved gaps from latest verification)
+  5. Plan-level inconsistencies? (tracking.json vs STATE.md mismatch, JOURNEY.md missing, roadmap drift)
+  6. Has any verification FAILED recently? Quote the FAIL summary if so.
+  7. Are there hard decisions (ADRs in decisions/) that constrain the next step?
+
+Keep it under 350 words. Be specific. No filler. Quote file:line for anything you assert.
+", subagent_type="Explore", description="Plan-view scan")
+```
+
+**Agent B — Code View** (unchanged from v1):
+
+```
+Agent(prompt="
+You are a read-only diagnostic scanner for the source code only.
+
+DO NOT read anything in .planning/ — skip it entirely.
+
+Scan the repo:
+  - Package/framework detection (package.json, requirements.txt, etc.)
+  - Entry points (app/, src/, pages/, index.*)
+  - Key files referenced in recent commits (git log --oneline -5, then inspect)
+  - Quick static checks: 'npx tsc --noEmit' output, lint errors, test status
+  - Stubs: grep for TODO, FIXME, 'not implemented', empty catch blocks, unused exports
+  - Dev server / deploy markers (vercel link, .env.local, supabase project ref)
+
+Produce a 'Code View' report answering:
+  1. What does the code LOOK LIKE it's building? (inferred from structure + imports)
+  2. What ACTUALLY WORKS right now? (compile status, recent commits, smoke signals)
+  3. What's STUBBED / INCOMPLETE? (concrete file:line citations)
+  4. What's RUNNING locally or deployed?
+  5. Code-level inconsistencies? (imports that don't resolve, routes referenced but not defined)
+
+Under 300 words. Cite file:line. No filler.
+", subagent_type="Explore", description="Code-view scan")
+```
+
+**Agent C — Conversation & Memory View** (new in v2):
+
+```
+Agent(prompt="
+You are a read-only diagnostic scanner for the user's recent activity. Do NOT read .planning/ or source code.
+
+Read:
+  - ${QUALIA_HOME}/knowledge/daily-log/<latest 1-2 dates>.md (recent session entries)
+  - ${QUALIA_HOME}/knowledge/concepts/<files referenced by the user's confusion>
+  - .continue-here.md (if present)
+  - git log --since='3 days ago' --oneline
+  - git diff main...HEAD --stat (work in flight)
+
+Cross-reference against the user's stated confusion: ${user_confusion}
+
+Produce a 'Session View' report answering:
+  1. What has the user been doing recently? (1-3 bullets from daily log + git)
+  2. Is the user's CURRENT confusion consistent with their recent activity, or is there a discontinuity? (e.g. they were in M2-P3 yesterday but today they're asking about M3 setup)
+  3. Are there saved learnings or ADRs that directly answer the user's confusion?
+  4. Was there a recent halt, FAIL, or pause we should foreground?
+
+Under 250 words. Quote daily-log line numbers or commit SHAs.
+", subagent_type="Explore", description="Session-view scan")
+```
+
+### Step 4. Synthesize — Diagnosis + Command Sequence
+
+With all three reports + `<user_confusion>` + `<session_context>` in hand, produce **exactly this shape**:
+
+```markdown
+## What I see
+
+**The plan says:** {1-2 sentences — current milestone/phase/status, what should be true}
+
+**The code says:** {1-2 sentences — what actually exists, what works, what's stubbed}
+
+**Your recent activity:** {1-2 sentences — last 2-3 days of work in flight, last commit, last skill run}
+
+**The mismatch (if any):** {1-2 sentences — where plan / code / activity disagree. If consistent, say "all three views align".}
+
+## What I think is happening
+
+{3-5 sentences, plain language. Tie the user's confusion to what you found. No jargon. If the user said "the login is broken", don't say "the auth middleware has a type inference issue" — say "you're seeing the login fail because the signin function isn't actually imported into the login page, even though phase-2-plan.md says it should be. Someone wrote the helper but forgot to wire it up — that's why verification went FAIL yesterday."}
+
+## What to do next — paste-ready command sequence
+
+```
+{command 1}      # {one-line reason}
+{command 2}      # {one-line reason}
+{command 3}      # {one-line reason}
+```
+
+{One sentence on what this sequence accomplishes end-to-end.}
+
+## Or, if you'd rather hand-pick:
+
+1. **{action}** — {why}
+2. **{action}** — {why}
+3. **{optional}** — {why}
+```
+
+**Command-sequence picking rules** — choose from these established patterns:
+
+| Situation found | Sequence |
+|---|---|
+| Plan says built but code has stubs | `/qualia-plan {N} --gaps` → `/qualia-build` → `/qualia-verify` |
+| Verify FAILed and no postmortem ran | `/qualia-postmortem` → `/qualia-plan {N} --gaps` → `/qualia-build` |
+| Stale `.continue-here.md`, ongoing context | `/qualia-resume` → `/qualia` |
+| Brownfield drift (plan and code diverged hard) | `/qualia-map` → `/qualia-plan {N} --gaps` |
+| Phase context missing (no `/qualia-discuss` ran) | `/qualia-discuss {N}` → `/qualia-plan {N}` |
+| Specific error, scope clear | `/qualia-fix '<symptom>'` |
+| Performance feels off, no profile | `/qualia-fix --perf '<route>'` or `/qualia-optimize --perf` |
+| Design feels off | `/qualia-polish --critique` then `/qualia-polish` |
+| User is overwhelmed | `/qualia-pause` (save handoff), come back later |
+| Truly nothing actionable found | Ask one specific question; don't invent a sequence |
+
+Pick the sequence that fits the actual evidence. Substitute real `{N}` from the Plan-view scan.
+
+### Step 5. Close
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js divider
+node ${QUALIA_BIN}/qualia-ui.js end "DIAGNOSED" "{first command in the sequence, if any}"
+```
+
+## Rules
+
+1. **Three isolated scans, always.** Plan view never peeks at code or session. Code view never peeks at planning. Session view never peeks at code. This is what keeps the diagnosis honest — each agent sees one slice, the synthesis catches the delta.
+2. **Plain language over jargon.** If you can't explain it to a non-dev, rewrite it.
+3. **No fake certainty.** If the scans come back thin (brand-new repo, no planning artifacts yet), say so explicitly: "I don't have enough signal yet — here's what I'd do to gather more."
+4. **Never invent facts.** If a scan didn't find something, don't claim it. Cite files.
+5. **Command sequence > single recommendation.** The user came here because one command isn't enough. Give them a chain.
+6. **The sequence must be paste-ready.** Real `{N}` values, real route names, no `<placeholder>` text outside the optional "if you'd rather hand-pick" section.
+7. **Don't re-run if `/qualia` already knows.** If the user's confusion is purely "what's my next command", `/qualia` handles it cheaper — gently suggest it and stop.
+
+## When NOT to Use
+
+- User knows what they're doing and just wants the next command → `/qualia`
+- User has a specific error message they want fixed → `/qualia-fix '<symptom>'`
+- User wants to review code quality → `/qualia-review`
+- User wants to pause and come back → `/qualia-pause`
+
+`/qualia-idk` is specifically for **"I'm not sure what I'm even looking at"** situations. Route to sharper tools when the question is sharper.

package/skills/qualia-learn/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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'."
+description: "Save a learning, pattern, fix, or client preference to the knowledge base. Persists across projects + sessions. Triggers: 'remember this', 'save this pattern', 'learned something', 'client prefers'."
 allowed-tools:
   - Read
   - Write

package/skills/qualia-map/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-map
-description: "Map an existing codebase to infer architecture, stack, conventions, what's already built, AND adapt Qualia to the repo's existing tracker/labels/glossary conventions (onboarding). For brownfield projects — run BEFORE /qualia-new so Validated requirements get inferred from existing code and Qualia commands respect the repo's existing process. Triggers: 'map this codebase', 'onboard to existing project', 'brownfield setup', 'what's already built here', 'scan the repo', 'inherited a codebase', 'audit this project before planning'."
+description: "Map an existing codebase (architecture, stack, conventions, capabilities) and adapt Qualia to its tracker/labels/glossary. Run BEFORE /qualia-new on brownfield projects. Triggers: 'map this codebase', 'onboard to existing project', 'brownfield setup', 'scan the repo', 'inherited a codebase'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-milestone/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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. Triggers: 'close milestone', 'next milestone', 'milestone done', 'wrap up milestone', 'M1 done open M2', 'I want to advance to the next milestone', 'finish this milestone'."
+description: "Close current milestone and open next — loads scope from JOURNEY.md (no ad-hoc naming), archives, regenerates ROADMAP.md. Triggers: 'close milestone', 'next milestone', 'milestone done', 'M1 done open M2'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-new/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-new
-description: "Set up a new project from scratch — deep questioning, ALWAYS-AUTO research, CONTEXT.md domain glossary seed, decisions/ ADR folder initialized, JOURNEY.md with all milestones to handoff, single approval gate, optional auto-chain into building. Use when starting any new client project."
+description: "Set up a new project — kickoff interview, research, CONTEXT.md glossary, decisions/ ADRs, JOURNEY.md, single approval gate, optional `--auto`. Triggers: 'new project', 'start a project', 'qualia-new', 'set up'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-optimize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-optimize
-description: "Deep improvement discovery pass — reads .planning/ AND codebase to find performance, design, UI, backend, frontend, alignment, and architecture-deepening opportunities. Spawns parallel specialist agents and writes OPTIMIZE.md/RFCs; practical repair work routes to /qualia-fix or /qualia-polish. Use when the user says 'optimize', 'optimization pass', 'find issues', 'deep improve', 'performance audit', 'design alignment check', 'speed up', 'bundle size', 'refactor architecture', 'shallow modules', 'simplify', or wants a comprehensive quality sweep. Supports --perf, --ui, --backend, --alignment, --deepen, --fix flags."
+description: "Deep improvement discovery pass — spawns parallel specialist agents and writes OPTIMIZE.md/RFCs. Triggers: 'optimize', 'find issues', 'performance audit', 'design alignment check', 'speed up', 'bundle size', 'shallow modules', 'simplify'. Flags: --perf, --ui, --backend, --alignment, --deepen, --fix. Routes practical repair to /qualia-fix or /qualia-polish."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-plan
-description: "Plans the current phase by spawning a planner agent to break it into executable tasks with waves, then validates via a plan-checker revision loop (max 2 cycles). Supports gap-closure mode for verification failures. Use when the user says 'plan this phase', 'break this into tasks', 'create the plan', 'qualia-plan', 'plan phase 2', or after /qualia-new sets up the journey."
+description: "Plan the current phase — planner agent breaks it into wave-grouped tasks, plan-checker validates (max 2 cycles). Supports `--gaps` for verification-failure closure. Triggers: 'plan this phase', 'break this into tasks', 'plan phase 2'."
 allowed-tools:
   - Bash
   - Read

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, 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."
+description: "Scope-adaptive visual quality pass — component, route, whole app, redesign, vibe pivot, or autonomous loop. Triggers: 'polish', 'design pass', 'redesign', 'critique', 'looks ugly', 'different vibe', 'visual loop'. Route functional bugs to /qualia-fix."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-postmortem/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-postmortem
-description: "Self-healing AI layer — when /qualia-verify returns FAIL, identify which agent/rule/skill should have caught the failure and propose a delta to that file so the same class of bug never recurs. Trigger on 'postmortem', 'why did the framework miss this', 'self-heal', 'qualia-postmortem', or auto-invoked by /qualia-verify on FAIL with --auto."
+description: "Self-healing pass — on /qualia-verify FAIL, identify which rule/agent/skill should have caught it and propose a delta. Triggers: 'postmortem', 'why did the framework miss this', 'self-heal'. Auto-invoked by /qualia-verify on FAIL with `--auto`."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-report/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-report
-description: "Generate session report, commit to git, push, and upload to the Qualia ERP — the mandatory clock-out flow. Use when the user says 'qualia-report', 'clock out', 'end of day', 'wrap up', 'session report', 'submit report', 'I'm done for today', or before stopping work. Handles empty days (no commits), missing API key, ERP outages, and dry-run preview gracefully."
+description: "Mandatory clock-out flow — generate session report, commit, push, upload to ERP. Handles empty days, missing API key, ERP outages, dry-run. Triggers: 'qualia-report', 'clock out', 'end of day', 'session report', 'I'm done for today'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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. Triggers: 'research X library', 'research the domain before planning', 'study Stripe webhooks', 'how do others do RAG', 'best practices for X', 'compare libraries', 'I need depth before planning phase N'. Distinct from /qualia-recall (which queries the local Obsidian vault) and /qualia-discuss (which interviews the user)."
+description: "Deep-research a domain or library BEFORE planning a phase. Spawns researcher with Context7/WebFetch. Writes .planning/phase-{N}-research.md. Triggers: 'research X library', 'study Stripe webhooks', 'best practices for X', 'compare libraries'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-review
-description: "Read-only production audit with scored diagnostics. Runs real commands, scores findings by severity, writes REVIEW.md, and routes repair work to /qualia-fix, /qualia-polish, or /qualia-optimize. Trigger on 'review', 'audit', 'code review', 'security check', 'production check'."
+description: "Read-only production audit — real commands, severity-scored REVIEW.md, routes repair to /qualia-fix, /qualia-polish, or /qualia-optimize. Triggers: 'review', 'audit', 'code review', 'security check', 'production check'."
 allowed-tools:
   - Bash
   - Read

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. 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. For headless/SSH/no-browser sessions. Triggers: 'show me the road', 'what's the workflow', 'how does Qualia work', SSH context."
 disable-model-invocation: true
 allowed-tools:
   - Read

package/skills/qualia-secure/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: qualia-secure
+description: "Security scan of agent config — CLAUDE.md / settings.json / hooks / MCP — for prompt injection, leaked secrets, unscoped permissions, config drift. Static pass + optional Opus red/blue/auditor pipeline. Triggers: 'security scan', 'security audit', 'check my config', 'before going live'."
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Agent
+---
+
+# /qualia-secure — Security audit of the agent's own configuration
+
+Not application code security. **Agent configuration security.** This skill audits the surfaces that Claude/Codex itself reads — CLAUDE.md, settings.json, hooks, MCP servers — for the class of risks that a normal linter cannot catch: prompt-injection vectors, secrets baked into instructions, unscoped tool permissions, drifted policy enforcement.
+
+This is Qualia's vertical equivalent of ECC's AgentShield, kept local to your stack.
+
+## When to run
+
+- **Before going live** with a new agent harness on a sensitive project.
+- **After installing new MCP servers** — each MCP description consumes context AND can introduce permission scope risks.
+- **As a release gate** — wire into CI via `qualia-framework secure --exit-code`.
+- **After editing CLAUDE.md / settings.json by hand** to catch accidental secret leaks or permission widening.
+
+## Process
+
+### Step 0. Banner
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js banner secure
+```
+
+Say: **"Running security scan."**
+
+### Step 1. Fast static pass
+
+```bash
+node ${QUALIA_BIN}/security-scan.js --write
+```
+
+This writes `.planning/security-scan.md` with severity-ranked findings:
+
+- **Secret patterns** — Anthropic / OpenAI / GitHub / AWS / Supabase JWT / Vercel keys baked into CLAUDE.md or settings.json (CRITICAL/HIGH).
+- **Permission smells** — unscoped `Bash` tool, `service_role` imports leaking into client code (CRITICAL/HIGH).
+- **Hook hygiene** — `child_process.exec` with `shell: true` from user input, hooks missing timeouts (MEDIUM/LOW).
+
+Read the report. If CRITICAL findings exist, **stop here** and rotate / fix before continuing — the deep pass is moot until the obvious holes are closed.
+
+### Step 2. Opus 4.7 adversarial deep-analysis (optional, longer)
+
+If the static pass is clean (or you want adversarial reasoning over the rules + instructions text regardless), run:
+
+```bash
+node ${QUALIA_BIN}/security-scan.js --deep
+```
+
+This writes:
+- `.planning/security-scan.md` (the static findings, same as Step 1)
+- `.planning/security-deep-prompt.md` (a prompt pack with the static findings as seeds, plus the three agent prompts ready to dispatch)
+
+Read `.planning/security-deep-prompt.md`. It contains three sections — RED TEAM, BLUE TEAM, AUDITOR — each is a self-contained prompt for one `Agent()` spawn. Dispatch the first two in parallel, then the auditor after they return:
+
+```
+Agent(prompt=<contents of "## Agent A — RED TEAM" section>, subagent_type="general-purpose", description="Red-team attacks")
+Agent(prompt=<contents of "## Agent B — BLUE TEAM" section>, subagent_type="general-purpose", description="Blue-team guardrail audit")
+```
+
+Wait for both. Pass their reports into the auditor:
+
+```
+Agent(prompt=<"## Agent C — AUDITOR" section> + "\n\n## Red-team output\n\n" + <A's report> + "\n\n## Blue-team output\n\n" + <B's report>, subagent_type="general-purpose", description="Auditor synthesis")
+```
+
+The auditor writes `.planning/security-audit.md` — that's the deliverable.
+
+### Step 3. Synthesize + route
+
+Combine `.planning/security-scan.md` (static) + `.planning/security-audit.md` (Opus) into a single executive summary. Surface the top 3 actions ranked by severity:
+
+- **CRITICAL** → fix immediately, before any further work.
+- **HIGH** → ticket for this sprint; route to `/qualia-hook-gen` if the fix is "make this instructional rule deterministic via a hook."
+- **MEDIUM/LOW** → backlog.
+
+### Step 4. Close
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js end "SECURED" "/qualia-hook-gen"
+```
+
+(Or omit the next-command if all findings are LOW.)
+
+## Rules
+
+1. **Static pass is non-negotiable.** It's fast and deterministic — always runs.
+2. **Opus pass is opt-in.** It costs tokens and time. Default to skipping unless the user explicitly asks for "deep audit" or the static pass triggers HIGH+ findings.
+3. **No fake severity.** Per `rules/grounding.md`, every finding cites `file:line` and matches a category in the Severity Rubric. No hedging.
+4. **Recommend deterministic fixes when possible.** A rule in CLAUDE.md is suggestive; a hook is enforced. The skill's bias is toward `/qualia-hook-gen` over "tell the agent to do X."
+5. **Never auto-rotate secrets.** Flag and instruct. The user rotates manually with confirmation — secrets in CI variables are the user's domain.
+
+## When NOT to use
+
+- Application-level security review (use `/security-review` for OWASP-style code audit).
+- Production deployment health (use `/qualia-doctor` / `/qualia-status`).
+- Specific bug investigation (use `/qualia-debug` → `/qualia-fix`).
+
+`/qualia-secure` is specifically for **the agent's configuration**. The hooks, the rules, the tool scopes, the MCP servers — the surfaces Claude reads to decide what to do.

package/skills/qualia-test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-test
-description: "Generate tests for existing code, run tests, OR drive a feature test-first via --tdd vertical-slice loop (red→green→refactor, one test→one impl→repeat). Trigger on 'write tests', 'add tests', 'test this', 'run tests', 'test coverage', 'need tests for', 'tdd this', 'test-driven', 'red green refactor'."
+description: "Generate tests, run tests, or drive a feature test-first via `--tdd` vertical-slice loop. Triggers: 'write tests', 'add tests', 'run tests', 'test coverage', 'tdd this', 'test-driven', 'red green refactor'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-verify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-verify
-description: "Goal-backward verification of a built phase. Spawns a fresh verifier agent that greps the actual codebase against acceptance criteria, scores the design rubric, and optionally runs an adversarial second pass. Use when the user says 'verify this phase', 'check if it works', 'run verification', 'did the build pass', 'qualia-verify', or after /qualia-build completes."
+description: "Goal-backward verification of a built phase — fresh verifier agent greps code against acceptance criteria, scores design rubric, optional adversarial second pass. Triggers: 'verify this phase', 'check if it works', 'run verification', 'did the build pass'."
 allowed-tools:
   - Bash
   - Read

package/skills/zoho-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zoho-workflow
-description: "Zoho Invoice and Mail operations via ERP-first routing. Creates invoices from templates, sends cover emails, manages contacts, reads inbox, and handles payment reminders. Use when the user says 'invoice this client', 'send an email', 'check inbox', 'create a Zoho contact', 'send payment reminder', or mentions invoicing, billing, or Zoho."
+description: "Zoho Invoice + Mail ops via ERP-first routing. Invoices from templates, cover emails, contacts, inbox, payment reminders. Triggers: 'invoice this client', 'send an email', 'check inbox', 'create a Zoho contact', 'payment reminder'."
 tags: [zoho, invoice, email, billing, crm]
 ---
 

package/tests/bin.test.sh

@@ -487,13 +487,14 @@ else
   fail_case "CLAUDE.md role substitution"
 fi
 
-# 31. All 12 hooks installed (block-env-edit removed in v3.2.0;
+# 31. All 13 hooks installed (block-env-edit removed in v3.2.0;
 # git-guardrails + stop-session-log added in v4.2.0;
 # vercel-account-guard + env-empty-guard + supabase-destructive-guard added in v5.0.0;
-# pre-compact removed in v6.2.0; fawzi-approval-guard added in v6.2.11)
+# fawzi-approval-guard added in v6.2.11; pre-compact removed in v6.2.0 and
+# REINTRODUCED in v6.3.2 with sidecar-snapshot mechanism)
 HOOK_COUNT=$(ls "$TMP/.claude/hooks/"*.js 2>/dev/null | wc -l)
-if [ "$HOOK_COUNT" -eq 12 ]; then
-  pass "12 hooks installed in hooks/"
+if [ "$HOOK_COUNT" -eq 13 ]; then
+  pass "13 hooks installed in hooks/ (incl. pre-compact v6.3.2)"
 else
   fail_case "hook count" "got $HOOK_COUNT"
 fi
@@ -509,8 +510,7 @@ else
   fail_case "settings.json contents"
 fi
 
-# 33. settings.json contains all 12 hooks wired correctly
-#     pre-compact.js was removed in v6.2.0 — verify it's NOT in settings.json.
+# 33. settings.json contains all 13 hooks wired correctly (v6.3.2 reintroduces pre-compact).
 if grep -q 'branch-guard.js' "$TMP/.claude/settings.json" \
    && grep -q 'migration-guard.js' "$TMP/.claude/settings.json" \
    && grep -q 'pre-push.js' "$TMP/.claude/settings.json" \
@@ -523,10 +523,10 @@ if grep -q 'branch-guard.js' "$TMP/.claude/settings.json" \
    && grep -q 'fawzi-approval-guard.js' "$TMP/.claude/settings.json" \
    && grep -q 'env-empty-guard.js' "$TMP/.claude/settings.json" \
    && grep -q 'supabase-destructive-guard.js' "$TMP/.claude/settings.json" \
-   && ! grep -q 'pre-compact.js' "$TMP/.claude/settings.json"; then
-  pass "settings.json has all 12 hooks wired (no pre-compact)"
+   && grep -q 'pre-compact.js' "$TMP/.claude/settings.json"; then
+  pass "settings.json has all 13 hooks wired (incl. pre-compact)"
 else
-  fail_case "settings.json hooks misconfigured (check for stale pre-compact entry)"
+  fail_case "settings.json hooks misconfigured"
 fi
 
 # 34. Lowercase code works (resolveTeamCode normalizes)

package/tests/install-smoke.test.sh

@@ -124,10 +124,10 @@ else
 fi
 
 if [ -d "$HOME_DIR/.claude/hooks" ] \
-  && [ "$(find "$HOME_DIR/.claude/hooks" -maxdepth 1 -name '*.js' | wc -l | tr -d ' ')" = "12" ] \
+  && [ "$(find "$HOME_DIR/.claude/hooks" -maxdepth 1 -name '*.js' | wc -l | tr -d ' ')" = "13" ] \
   && [ -f "$HOME_DIR/.claude/hooks/fawzi-approval-guard.js" ] \
-  && [ ! -f "$HOME_DIR/.claude/hooks/pre-compact.js" ]; then
-  pass "packaged install has 12 hooks and no pre-compact"
+  && [ -f "$HOME_DIR/.claude/hooks/pre-compact.js" ]; then
+  pass "packaged install has 13 hooks including pre-compact (v6.3.2 sidecar snapshot)"
 else
   fail_case "packaged hook set mismatch"
 fi