qualia-framework 6.2.10 → 6.3.0

package/skills/qualia-debug/SKILL.md

@@ -1,193 +0,0 @@
----
-name: qualia-debug
-description: "Investigation lane for unclear bugs and weird behavior. Parses symptoms, runs diagnostic scans, identifies root cause, and either reports insufficient evidence or routes actionable repair work to /qualia-fix. Trigger on 'debug', 'find bug', 'why is this broken', 'something is weird', 'investigate', 'root cause', 'not sure what's failing', 'CSS issue', 'slow page', 'performance'."
-allowed-tools:
-  - Bash
-  - Read
-  - Edit
-  - Write
-  - Grep
-  - Glob
-  - Agent
----
-
-# /qualia-debug — Investigative Debugging (one-shot)
-
-Parse the symptom. Run diagnostics. Find root cause. Write report, or route to `/qualia-fix` when the repair is actionable. **One-shot — no mandatory user questions.**
-
-## Usage
-
-- `/qualia-debug {symptom}` — investigate a specific symptom
-- `/qualia-debug` — no symptom given: investigate recently-changed files for obvious bugs
-- `/qualia-debug --frontend {symptom}` — layout/z-index/overflow bias
-- `/qualia-debug --perf {symptom}` — performance bias
-
-If the user says "fix it" and the expected behavior is known, prefer `/qualia-fix`. Debug is for uncertainty; fix is for repair.
-
-## Tool Budget
-
-Max 10 Read/Grep/Bash calls for investigation. If you haven't narrowed to root cause in 10, return `INSUFFICIENT EVIDENCE after 10 steps. Narrowed to: {files}. Recommend: {next diagnostic}.` Do not keep guessing.
-
-## Process
-
-```bash
-node ${QUALIA_BIN}/qualia-ui.js banner debug
-```
-
-### 1. Parse Symptom from $ARGUMENTS
-
-- If arguments provided → that's the symptom. Extract: what's broken, where (file/page/feature), when (on click? on load? after change?).
-- If arguments empty → run `git diff HEAD~3 --stat` to find recently-touched files. Treat those as the suspect set. Symptom = "something in recent changes".
-
-### 2. Check Known Fixes First (cheap)
-
-```bash
-node ${QUALIA_BIN}/knowledge.js search "{symptom_keywords}"
-```
-
-If a known fix matches, apply it and jump to step 5 (verify). Known fixes are pre-verified patterns — no need to re-investigate.
-
-### 3. Diagnostic Scan
-
-Run the scan matching the symptom type. All commands in a scan block run as parallel Bash calls in a single response turn.
-
-**General mode (default):**
-```bash
-# Compile errors
-npx tsc --noEmit 2>&1 | grep "error TS" | head -20
-
-# Empty catch / swallowed errors
-grep -rn "catch\s*{}\|catch\s*(.*)\s*{\s*}" --include="*.ts" --include="*.tsx" app/ components/ src/ lib/ 2>/dev/null | head -10
-
-# Recent console.error or thrown errors
-grep -rn "console\.error\|throw new" --include="*.ts" --include="*.tsx" app/ components/ src/ lib/ 2>/dev/null | head -10
-
-# Broken imports
-npx tsc --noEmit 2>&1 | grep -i "Cannot find module\|has no exported"
-```
-
-**Frontend mode (`--frontend`):**
-```bash
-# Stacking context audit (z-index issues)
-grep -rn "z-index\|z-\[" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null | head -20
-
-# Overflow candidates (horizontal scroll, clipping)
-grep -rn "100vw\|overflow.*hidden\|overflow-x\|position.*fixed" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null | head -15
-
-# Fixed dimensions breaking mobile
-grep -rn "width:.*[0-9]\+px\|height:.*[0-9]\+px\|w-\[[0-9]\+px\|h-\[[0-9]\+px" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null | grep -v "min-\|max-" | head -10
-
-# Flex/grid blowout candidates
-grep -rn "flex\|grid" --include="*.tsx" app/ components/ src/ 2>/dev/null | grep -v "min-w-0\|minmax(0" | wc -l
-```
-
-**Perf mode (`--perf`):**
-```bash
-# Sequential awaits that should be Promise.all
-grep -rn "const.*=.*await" --include="*.tsx" --include="*.ts" app/ src/ 2>/dev/null | grep -v "Promise.all\|Promise.allSettled" | head -15
-
-# Large files
-find app/ components/ src/ -name "*.tsx" -o -name "*.ts" 2>/dev/null | xargs wc -l 2>/dev/null | sort -rn | head -10
-
-# Missing next/image
-grep -rn "<img " --include="*.tsx" --include="*.jsx" app/ components/ src/ 2>/dev/null | grep -v "next/image" | wc -l
-
-# No dynamic imports (possible big bundles)
-grep -rn "import(\|next/dynamic" --include="*.tsx" --include="*.ts" app/ src/ 2>/dev/null | wc -l
-
-# Client-boundary usage
-grep -rln "'use client'" --include="*.tsx" app/ components/ src/ 2>/dev/null | wc -l
-```
-
-### 4. Form Hypothesis + Route or Apply Minimal Fix
-
-From the diagnostic output, state the root cause in one sentence with `file:line` citation. No hedging — either you have evidence or you write `INSUFFICIENT EVIDENCE` and return (step 6).
-
-If the user explicitly asked for repair and the fix is <= 3 files, route to `/qualia-fix {symptom}` with the root cause summary. If this debug invocation is already mid-repair, apply the minimal fix here for backward compatibility.
-
-Apply the minimal fix:
-- Only edit files whose contents caused the symptom
-- One concept per commit — don't fold in cleanup
-- Don't refactor adjacent code
-- If the fix touches > 3 files, stop and ask the user first (major refactor disguised as a debug)
-
-### 5. Verify Fix
-
-```bash
-# TypeScript still compiles?
-npx tsc --noEmit 2>&1 | grep -c "error TS"   # Expect 0
-
-# Symptom reproduction — ideally a grep that would have matched the bug
-# and now returns empty:
-grep -rn "{pattern that represented the bug}" {scope} 2>/dev/null
-```
-
-If the verification fails, revert and return to step 3 with narrower hypothesis.
-
-### 6. Write DEBUG Report
-
-Create the report directory and write to `.planning/reports/debug/DEBUG-{YYYY-MM-DD-HHMM}.md`:
-
-```bash
-mkdir -p .planning/reports/debug
-```
-
-```markdown
-# Debug Report — {YYYY-MM-DD HH:MM}
-
-**Symptom:** {user description or "recent changes" if no args}
-**Mode:** general | frontend | perf
-**Tool calls used:** {N}/10
-
-## Investigation
-- Diagnostic scans run: {list}
-- Files examined: {list}
-- Patterns searched: {list}
-
-## Root Cause
-{file:line} — "{quoted problematic code}" — {explanation of why it caused the symptom}
-
-## Fix Applied
-- Files: {list}
-- Diff summary: {one paragraph}
-- Verification: {commands run + results}
-
-## Related Observations
-- {any adjacent issues noticed but NOT fixed in this debug pass}
-```
-
-### 7. Commit
-
-```bash
-git add {specific files you changed}
-git commit -m "fix: {what was broken and why}"
-```
-
-## INSUFFICIENT EVIDENCE Return
-
-If you exhaust the 10-call budget without a confident root cause:
-
-```markdown
-# Debug Report — {YYYY-MM-DD HH:MM}
-
-**Symptom:** {description}
-**Outcome:** INSUFFICIENT EVIDENCE after 10 inspection steps
-
-## Narrowed To
-- Files examined: {list}
-- Ruled out: {list}
-- Remaining suspects: {list}
-
-## Recommended Next Diagnostic
-- {specific next step for the user — e.g., "run `npm run dev` and watch browser console for the specific error", or "add console.log at file:line and reproduce"}
-```
-
-Do NOT apply a speculative fix. Return the report and stop.
-
-## Rules
-
-- **No mandatory questions.** This is one-shot. If symptom args are missing, investigate recent changes.
-- **Root cause or INSUFFICIENT EVIDENCE** — no "probably" fixes.
-- **Minimal fix only.** One concept, one commit. No refactors dressed as debug. Prefer `/qualia-fix` for explicit repair requests.
-- **Tool budget is hard.** 10 calls, then stop.
-- **Every investigation gets a DEBUG report in `.planning/reports/debug/`** — creates a searchable record without cluttering the root.

package/skills/qualia-flush/SKILL.md

@@ -1,198 +0,0 @@
----
-name: qualia-flush
-description: "Promote daily-log raw entries to the curated knowledge tier — Karpathy-style raw→wiki flush. Reads ${QUALIA_KNOWLEDGE}/daily-log/*.md, identifies recurring patterns and decisions, writes them to ${QUALIA_KNOWLEDGE}/concepts/{topic}.md, updates index.md. Trigger on 'flush memory', 'promote learnings', 'consolidate logs', 'qualia-flush', 'process daily logs', or run weekly."
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
----
-
-# /qualia-flush — Promote Raw Daily Logs to Curated Concepts
-
-Closes the **raw → wiki** loop in the Qualia memory layer. The Stop hook
-(`hooks/stop-session-log.js`) appends mechanical session checkpoints to
-`${QUALIA_KNOWLEDGE}/daily-log/{date}.md`.
-Those entries accumulate but stay raw — they describe what happened, not
-what to do about it. This skill reads the recent daily-log entries with an
-LLM (you) and writes durable concepts that the builder, planner, and
-debug skills will surface later via `node ${QUALIA_BIN}/knowledge.js`.
-
-Inspired by Karpathy's LLM knowledge bases and Cole Medin's self-evolving
-Claude memory pattern (NotebookLM, 2026-04-25). Both run a daily/weekly
-flush that promotes raw observations into structured wiki articles. We do
-the same — manually-triggered, internal-data only, no vector DB.
-
-## When to run
-
-- **Manually:** `/qualia-flush` whenever the daily-log feels rich. Once a week
-  is the recommended cadence. More than once a day is wasteful — the
-  signal-to-noise ratio is too low at single-day windows.
-- **CLI runner:** `qualia-framework flush` wraps the cron-friendly
-  `bin/knowledge-flush.js` non-interactive runner.
-
-## Inputs
-
-- `--days N` (optional, default 14) — how many days of daily-log to consider
-- `--project NAME` (optional) — only flush entries for one project
-- `--dry-run` (optional) — print the proposed writes, don't touch disk
-
-If the user invokes the skill bare (no args), default to `--days 14` and
-all projects. Show a one-line preview before writing anything destructive.
-
-## Process
-
-### 1. Banner + check the floor
-
-```bash
-node ${QUALIA_BIN}/qualia-ui.js banner flush 2>/dev/null || true
-
-# Resolve the knowledge dir. Fail loud if it doesn't exist — flush is
-# meaningless without a daily-log to read.
-KNOWLEDGE_DIR="$HOME/.claude/knowledge"
-DAILY_DIR="$KNOWLEDGE_DIR/daily-log"
-if [ ! -d "$DAILY_DIR" ]; then
-  echo "QUALIA: No daily-log at $DAILY_DIR — Stop hook hasn't run yet, or knowledge layer wasn't initialized."
-  echo "Run: npx qualia-framework@latest install"
-  exit 1
-fi
-
-# Default 14-day window. Date math is cross-platform-safe with Node.
-WINDOW_DAYS="${WINDOW_DAYS:-14}"
-node -e "
-  const d = new Date();
-  d.setDate(d.getDate() - $WINDOW_DAYS);
-  console.log(d.toISOString().split('T')[0]);
-" > /tmp/qualia-flush-cutoff
-CUTOFF=$(cat /tmp/qualia-flush-cutoff)
-```
-
-### 2. Collect the daily-log entries in window
-
-```bash
-# Iterate every file in daily-log/ whose name (YYYY-MM-DD.md) is >= CUTOFF.
-# Concatenate them into one stream so the LLM (you) can scan as one corpus.
-ls "$DAILY_DIR"/*.md 2>/dev/null | while read -r f; do
-  base=$(basename "$f" .md)
-  if [ "$base" \> "$CUTOFF" ] || [ "$base" = "$CUTOFF" ]; then
-    echo "=== $base ==="
-    cat "$f"
-    echo ""
-  fi
-done
-```
-
-You now have the raw stream. Read it.
-
-### 3. Identify what's worth promoting
-
-Read every entry. Group by project. Look for these signals — these are
-the things that promote into the wiki:
-
-| Signal in raw entry | What to extract | Goes to |
-|---|---|---|
-| Same fix appears in 2+ sessions | A common fix recipe | `common-fixes.md` (via `knowledge.js append --type fix`) |
-| A pattern shows up in 3+ projects | A reusable pattern | `learned-patterns.md` (via `knowledge.js append --type pattern`) |
-| A client-name or project preference recurs | A client preference | `client-prefs.md` (via `knowledge.js append --type client`) |
-| A new technology/library used successfully | A stack note | `concepts/{tech}.md` (new file, Write directly) |
-| A recurring failure mode (verify-fail, regression) | A pitfall | `learned-patterns.md` framed as "anti-pattern: …" |
-
-Things to **NOT** promote:
-- Single-occurrence quirks (they're noise until they recur).
-- Bare commit/branch info — that's already in git, no value duplicating.
-- Anything containing secrets, tokens, customer PII. The knowledge layer
-  is plain markdown, never put secrets here.
-- Entries from `--dry-run` runs of other skills (they'll show as activity
-  but didn't actually do anything).
-
-### 4. Write the promotions
-
-For each thing worth promoting, use the loader's `append`:
-
-```bash
-node ${QUALIA_BIN}/knowledge.js append \
-  --type {pattern|fix|client} \
-  --title "{Concise title — what's the recurring thing?}" \
-  --body "{The promoted lesson. Be specific. Include the project name(s) and dates where this pattern was observed so future you can verify.}" \
-  --project "{specific project, or 'general' if cross-project}" \
-  --context "Promoted by /qualia-flush from daily-log entries on {dates}"
-```
-
-For a brand-new topic that doesn't fit pattern/fix/client (e.g. a Stripe
-integration approach worth its own file), Write to
-`${QUALIA_KNOWLEDGE}/concepts/{topic}.md`. Then **update `index.md`** so the
-new file is reachable — list it under "What's where" with one line:
-
-```bash
-# After writing concepts/stripe-checkout.md:
-node ${QUALIA_BIN}/knowledge.js path stripe-checkout
-# Returned path = ${QUALIA_KNOWLEDGE}/stripe-checkout.md  (NOTE: top-level, not concepts/)
-```
-
-> **Loader behavior:** `knowledge.js load <name>` resolves bare names by walking
-> top-level + subdirectories (`concepts/`, `daily-log/`) for an exact match.
-> Write durable entries to `concepts/{topic}.md`; the loader will find them.
-
-### 5. Mark the window as flushed
-
-Write a stamp file so subsequent flushes can default to "since the last
-flush" instead of "last 14 days":
-
-```bash
-date -u +%Y-%m-%dT%H:%M:%SZ > "$HOME/.claude/.qualia-last-flush"
-```
-
-### 6. Summarize
-
-Print to the user, in plain language:
-
-- N daily-log files scanned (date range)
-- M promotions written (with file:title for each)
-- K things considered but not promoted (single-occurrence — wait for them to recur)
-
-Format:
-
-```
-⬢ Flushed daily-log {start} → {end} ({N} files, {total entries} entries)
-  Promoted to wiki:
-    + learned-patterns.md  "Supabase RLS in same migration"  (3 sessions, 2 projects)
-    + common-fixes.md      "next/font crash on Vercel"       (2 sessions)
-    + concepts/voice-agent-call-state.md  (new file)
-  Skipped {K} single-occurrence entries — will revisit if they recur.
-```
-
-## Style
-
-- **Be conservative.** False-positive promotions (writing noise as if it's a
-  pattern) pollute the wiki and erode trust. Better to skip a candidate and
-  let it recur next week than to inflate the curated tier.
-- **Cite your sources.** Every promoted entry should reference the
-  daily-log dates that sourced it, in the `--context` field. If a future
-  flush wants to update it, the trail is there.
-- **Keep titles short.** `--title "Supabase RLS same migration"` not `"You should always remember that when working with Supabase you need to..."`. The body is for nuance.
-- **Don't promote private projects across boundaries.** A pattern from
-  Project A is fine to promote as cross-project ONLY if it generalizes.
-  Client-specific things stay client-specific (`--type client --project X`).
-
-## Anti-patterns
-
-- **Mass-promoting everything:** if you found "promotions" for 90% of
-  daily-log entries, you're labeling, not promoting. Be selective.
-- **Re-promoting on every flush:** before appending, run
-  `node ${QUALIA_BIN}/knowledge.js search "{title keywords}"` to check if
-  the pattern already exists. If it does, either update it (find by `**ID:**`
-  line) or skip — never duplicate.
-- **Hand-writing to `learned-patterns.md` etc. directly:** always go
-  through `knowledge.js append` so the canonical entry format and ID
-  generation stay consistent. This skill is the only sanctioned promoter,
-  but even it uses the loader for writes.
-
-## Output contract
-
-If invoked with `--dry-run`, print the proposed writes and exit without
-touching disk. Otherwise, after step 6 returns the summary, the skill is
-done — no follow-up prompts. The user sees the summary and the wiki tier
-has new entries that are immediately reachable to every other skill via
-the loader.

package/skills/qualia-help/SKILL.md

@@ -1,74 +0,0 @@
----
-name: qualia-help
-description: "Open the BROWSER HTML reference for the Qualia Framework — themed page with all commands, rules, services, and the road. The default when a browser is available. For terminal-only output (SSH, headless), use /qualia-road. Triggers: 'help', 'how does this work', 'show me the commands', 'qualia help', 'reference', 'open the docs'."
-allowed-tools:
-  - Bash
-  - Read
----
-
-# /qualia-help — Framework Reference
-
-Opens a Qualia-themed HTML reference guide in your default browser.
-
-## Process
-
-### 1. Generate the HTML
-
-```bash
-# 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 in the user home, check the installed framework copy.
-if [ ! -f "$TEMPLATE" ]; then
-  for CANDIDATE in "$HOME/.claude/qualia-framework/templates/help.html"; do
-    if [ -f "$CANDIDATE" ]; then TEMPLATE="$CANDIDATE"; break; fi
-  done
-fi
-```
-
-### 2. Inject version and open
-
-```bash
-# Replace {{VERSION}} placeholder with actual version
-sed "s/{{VERSION}}/$VERSION/g" "$TEMPLATE" > "$OUTPUT"
-
-# Open in default browser (cross-platform)
-if command -v xdg-open &>/dev/null; then
-  xdg-open "$OUTPUT"          # Linux
-elif command -v open &>/dev/null; then
-  open "$OUTPUT"               # macOS
-elif command -v start &>/dev/null; then
-  start "$OUTPUT"              # Windows (Git Bash)
-else
-  echo "Open this file in your browser: $OUTPUT"
-fi
-```
-
-### 3. Confirm
-
-```bash
-node ${QUALIA_BIN}/qualia-ui.js banner router
-node ${QUALIA_BIN}/qualia-ui.js ok "Reference guide opened in browser"
-node ${QUALIA_BIN}/qualia-ui.js info "File: /tmp/qualia-help.html"
-```
-
-If the browser does not open automatically, tell the user the file path so they can open it manually.
-
-## Notes
-
-- The HTML file is self-contained — no external dependencies except Google Fonts
-- Works offline after first load (fonts cache)
-- Qualia-themed: dark background, teal accents, Outfit + Inter fonts
-- Shows: The Road, all commands grouped, verification scoring, rules, stack, GitHub orgs
-- Version is injected dynamically from .qualia-config.json

package/skills/qualia-hook-gen/SKILL.md

@@ -1,206 +0,0 @@
----
-name: qualia-hook-gen
-description: "Take a project's CLAUDE.md or rules/*.md instruction and convert it deterministically into a Claude Code pre-tool-use hook. Generates block-{cmd}.sh + the settings.json patch + activation steps. Lets users actually shrink their CLAUDE.md instead of just hearing the instruction-budget advice. Trigger on 'qualia-hook-gen', 'turn this rule into a hook', 'enforce this deterministically', 'block npm', 'force pnpm', 'convert claude.md to hooks', 'shrink my instruction budget'."
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-argument-hint: "[--rule \"text\"] [--from CLAUDE.md] [--name HOOK_NAME] [--scope global|project] [--dry-run]"
----
-
-# /qualia-hook-gen — Convert instructions → deterministic hooks
-
-LLMs have a realistic instruction budget of ~300-500 instructions before quality degrades (Matt Pocock). A line in CLAUDE.md like "use pnpm not npm" burns budget on EVERY request — even when the task has nothing to do with package management. Worse, it's non-deterministic: the model can still run `npm install` if it forgets.
-
-The fix: convert that instruction into a deterministic `pre-tool-use` hook. The hook blocks the wrong command (or rewrites it to the right one) at execution time, frees the instruction budget, and works regardless of context window state.
-
-## When to use
-
-- Your CLAUDE.md has 50+ lines and you want to slim it
-- A specific instruction is enforceable as a CLI rule (use X not Y, never run Z, redirect A to B)
-- You want a hook for a specific failure mode (e.g., "always use --force-with-lease, never --force")
-
-## What it does NOT do
-
-- Hooks for stylistic guidance (e.g., "prefer composition over inheritance") — that's not enforceable by command match. Stays in skills.
-- Hooks for non-deterministic checks (e.g., "validate the design feel"). Use `/qualia-polish` instead.
-- Hooks that need state across multiple commands. Use Qualia's existing state.js machinery.
-
-## Process
-
-### 1. Identify the rule
-
-Three input modes:
-
-| Mode | Source |
-|---|---|
-| `--rule "..."` | Direct argument (e.g. `--rule "use pnpm not npm"`) |
-| `--from CLAUDE.md` | Pull instructions from the file, list them, let user pick |
-| (no arg) | Read CLAUDE.md, scan for enforceable rules, propose top 3 candidates |
-
-### 2. Classify enforceability
-
-For the chosen rule, classify into one of three patterns:
-
-| Pattern | Example | Hook shape |
-|---|---|---|
-| **Block** | "never use `git push --force` to main" | exit 2 with message if pattern matches |
-| **Rewrite** | "use pnpm not npm" | exit 2 with message guiding to alternative |
-| **Warn** | "prefer next/image over <img>" | exit 0 but print warning to stderr |
-
-If the rule isn't classifiable as any of these — i.e. it's stylistic or judgment-based — HALT with: "This rule isn't deterministically enforceable. Keep it in CLAUDE.md or move to a skill. Examples of enforceable rules: package-manager redirects, destructive-command blocks, file-path enforcement."
-
-### 3. Generate the hook script
-
-Write to `hooks/block-{name}.js` (Node, cross-platform — same shape as existing hooks):
-
-```javascript
-#!/usr/bin/env node
-// hooks/block-{name}.js — auto-generated by /qualia-hook-gen
-// Original instruction: "{rule text}"
-// Pattern: {block | rewrite | warn}
-// Generated: {ISO date}
-
-const { readFileSync } = require("fs");
-let payload;
-try { payload = JSON.parse(readFileSync(0, "utf8")); } catch { process.exit(0); }
-const cmd = (payload.tool_input && payload.tool_input.command) || "";
-
-// Match condition (regex from rule classification)
-if (!/{matcher}/i.test(cmd)) process.exit(0);  // not our concern
-
-// Action
-console.error("⚠ Qualia hook ({name}): {message}");
-console.error("   Suggested: {suggested_alt}");
-process.exit(2);  // 2 = BLOCK in Claude Code hook protocol
-```
-
-The exact matcher + message + suggestion are filled by the synthesizer based on the rule classification.
-
-### 4. Generate the settings.json patch
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "if": "Bash({if-condition})",
-            "command": "node \"${HOME}/.claude/hooks/block-{name}.js\"",
-            "timeout": 5,
-            "statusMessage": "⬢ Checking {what}..."
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-The `if` condition narrows when the hook fires (e.g., `Bash(npm*)` to fire only on npm). Saves cycles by skipping the hook entirely on irrelevant commands.
-
-### 5. Test the hook
-
-```bash
-# Simulate a triggering command
-echo '{"tool_input":{"command":"{triggering_example}"}}' | \
-  node hooks/block-{name}.js
-echo "Exit: $?"   # should be 2
-
-# Simulate a non-triggering command
-echo '{"tool_input":{"command":"{safe_example}"}}' | \
-  node hooks/block-{name}.js
-echo "Exit: $?"   # should be 0
-```
-
-If the test passes, proceed. If not, debug the matcher regex.
-
-### 6. Activate
-
-Two scopes:
-
-| Scope | Action |
-|---|---|
-| `--scope project` (default for project rules) | Add the patch to `.claude/settings.json` in the project root |
-| `--scope global` | Add to `${QUALIA_HOME}/settings.json`. Use only if rule applies to ALL projects |
-
-Use the existing settings-merge logic from `bin/install.js:756-778` (preserves user fields, atomic write, backup-before-overwrite).
-
-### 7. Suggest CLAUDE.md slim
-
-After activating, scan CLAUDE.md / `rules/*.md` for the original instruction. If found, suggest the user remove it (don't auto-remove — let the user verify the hook works first):
-
-```
-✓ Hook installed: hooks/block-{name}.js
-✓ Settings patched: .claude/settings.json
-ℹ You can now remove this line from CLAUDE.md (the hook enforces it deterministically):
-    > "{original instruction}"
-ℹ Test with: echo '{"tool_input":{"command":"{triggering_example}"}}' | node hooks/block-{name}.js
-```
-
-### 8. Commit
-
-```bash
-git add hooks/block-{name}.js .claude/settings.json
-git -c user.name="Qualia Solutions" -c user.email="info@qualiasolutions.net" \
-  commit -m "feat(hook): block-{name} — enforces \"{rule}\" deterministically"
-```
-
-## Examples
-
-**Block npm in favor of pnpm:**
-```
-/qualia-hook-gen --rule "use pnpm not npm"
-→ hooks/block-npm.js  (matches /^\s*npm\s+(install|i|run|exec)/, exit 2)
-→ .claude/settings.json  (PreToolUse > Bash > if: Bash(npm*))
-→ "npm install" now blocks with: "Use pnpm not npm. Run: pnpm install"
-```
-
-**Block destructive git on main:**
-```
-/qualia-hook-gen --rule "never push --force to main"
-→ hooks/block-force-push-main.js  (matches /git push.*--force.*main/)
-→ Already covered by hooks/git-guardrails.js — surface this overlap and skip
-```
-
-**Force /server/ for service_role usage:**
-```
-/qualia-hook-gen --rule "service_role only in lib/server/*"
-→ Not enforceable as a CLI hook (it's a code-level rule).
-→ HALT with recommendation: ESLint rule or pre-deploy-gate.js entry instead.
-```
-
-## Token discipline
-
-This skill itself is short by design (~150 lines SKILL.md). REFERENCE.md (if added later) only carries verbatim hook templates. The whole point of `/qualia-hook-gen` is to REDUCE token cost across a project, not add to it.
-
-Per-invocation: ~3K tokens for the rule-classification + hook-template synthesis. Net savings: every subsequent request saves the ~50-200 tokens that the moved CLAUDE.md instruction was costing.
-
-## Failure modes
-
-| Symptom | Cause | Action |
-|---|---|---|
-| Rule isn't a CLI command | Stylistic / judgment-based | HALT with recommendation: skill or ESLint rule |
-| Matcher would catch too much | Regex too greedy | Tighten with `--name` and explicit pattern; user-confirm before write |
-| Hook conflicts with existing | Same command already hooked | Surface the conflict; refuse to overwrite without `--force` |
-| Settings.json malformed | Pre-existing bad JSON | Refuse to patch; ask user to fix settings.json first |
-| `node` not on hook PATH | Cross-platform issue | Use `process.execPath` resolution; framework's existing hooks handle this |
-
-## Rules
-
-1. **Hook is determinism, skill is guidance.** Hooks can only block/rewrite/warn on CLI patterns. Stylistic rules stay in skills.
-2. **Never overwrite an existing hook silently.** If `hooks/block-{name}.js` exists, surface and ask.
-3. **Test before committing.** The hook must pass the trigger + non-trigger smoke tests before commit.
-4. **Suggest CLAUDE.md cleanup.** After install, surface the now-redundant CLAUDE.md line. Don't auto-delete — user verifies the hook works first.
-5. **Match Qualia's hook shape.** All hooks are pure Node, cross-platform, exit 0/2. No `.sh` scripts (Windows compat).
-
-## Pairs with
-
-- `/qualia-optimize --deepen` — runs sometimes after a hook-gen pass when CLAUDE.md gets short enough that the codebase architecture becomes the next bottleneck
-- Existing hooks: `git-guardrails.js`, `pre-deploy-gate.js`, `vercel-account-guard.js`, `env-empty-guard.js`, `supabase-destructive-guard.js`. New hooks generated by this skill follow the same conventions.