qualia-framework 6.2.9 → 6.3.0

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 ~/.claude/knowledge/daily-log/*.md, identifies recurring patterns and decisions, writes them to ~/.claude/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
-`~/.claude/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 ~/.claude/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 ~/.claude/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 ~/.claude/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
-`~/.claude/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 ~/.claude/bin/knowledge.js path stripe-checkout
-# Returned path = ~/.claude/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 ~/.claude/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 ~/.claude/bin/qualia-ui.js banner router
-node ~/.claude/bin/qualia-ui.js ok "Reference guide opened in browser"
-node ~/.claude/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 `~/.claude/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.

package/skills/qualia-idk/SKILL.md

@@ -1,166 +0,0 @@
----
-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"
-
-Not a router. A **diagnostician**. Use when the user isn't stuck on a command — they're stuck on *understanding*.
-
-## How This Differs from `/qualia`
-
-| `/qualia` | `/qualia-idk` |
-|---|---|
-| Mechanical: reads state.js, returns `/qualia-X` | Interpretive: reads the project + the code + the confusion |
-| "What command do I run next?" | "What is actually going on here?" |
-| Always returns a skill name | Returns an explanation + a recommendation |
-| Cheap, instant | Spawns 2 isolated agents, ~30s |
-
-Run `/qualia` first when the user knows what they're trying to do. Run `/qualia-idk` when the user's confusion is about the *situation itself*.
-
-## Process
-
-### Step 0. Banner
-
-```bash
-node ~/.claude/bin/qualia-ui.js banner router
-node ~/.claude/bin/qualia-ui.js spawn "diagnostic" "Reading planning and codebase in isolation..."
-```
-
-Say: **"Let me take a proper look."**
-
-### Step 1. Gather the User's Confusion
-
-Look at the conversation context (if any). 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?
-
-If there's nothing in conversation context yet, ask:
-- header: "What's unclear?"
-- question: "Where are you stuck? (one sentence is fine)"
-- Free text.
-
-Store this as `<user_confusion>`.
-
-### Step 2. Spawn Two Isolated Scans (Parallel)
-
-Two fresh subagents. Each sees ONLY its respective scope — no cross-contamination.
-
-```
-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/JOURNEY.md
-  - .planning/REQUIREMENTS.md
-  - .planning/ROADMAP.md
-  - .planning/STATE.md
-  - .planning/tracking.json
-  - .planning/phase-*-plan.md (latest 1-2)
-  - .planning/phase-*-verification.md (latest 1-2)
-  - .planning/DESIGN.md (skim)
-  - .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 + phase + status)
-  3. What does the plan say should be TRUE right now? (current phase's acceptance criteria / success criteria)
-  4. What does the plan say is UNFINISHED? (upcoming phases or unresolved gaps from latest verification)
-  5. Any plan-level inconsistencies? (e.g. tracking.json says phase 3 but STATE.md says phase 2, JOURNEY.md missing, roadmap out of sync)
-
-Keep it under 250 words. Be specific. No filler.
-", subagent_type="Explore", description="Plan-view scan")
-
-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)
-  - Run quick static checks if applicable: 'npx tsc --noEmit' output, lint errors, test status
-  - Look for stubs: grep for TODO, FIXME, 'not implemented', empty catch blocks, unused exports
-
-Produce a 'Code View' report answering:
-  1. What does the code look like it's BUILDING? (inferred from structure + imports, not from docs)
-  2. What ACTUALLY WORKS right now? (compile status, recent commit messages, any obvious smoke signals)
-  3. What's STUBBED or INCOMPLETE? (concrete file:line citations)
-  4. What's RUNNING locally or deployed? (if there's a dev server log, vercel link, supabase project — flag it)
-  5. Any code-level inconsistencies? (imports that don't resolve, routes referenced but not defined, schema mismatches)
-
-Keep it under 250 words. Cite specific files/lines. No filler.
-", subagent_type="Explore", description="Code-view scan")
-```
-
-Wait for both. Don't proceed to synthesis until you have both reports.
-
-### Step 3. Synthesize
-
-With both reports + the user's confusion in hand, cross-reference:
-
-**Produce a structured diagnosis** (use this exact shape):
-
-```
-## 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}
-
-**The mismatch (if any):** {1-2 sentences — where plan and code disagree. If no mismatch, say "plan and code are consistent".}
-
-## What I think is happening
-
-{3-5 sentences, plain language. Tie the user's confusion to what you found. Avoid 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 the plan says it should be. Someone wrote the helper but forgot to wire it up."}
-
-## What to do next
-
-1. **{concrete action}** — {one sentence why}
-2. **{concrete action}** — {one sentence why}
-3. **{optional third}** — {one sentence why}
-
-If one of these maps to an existing Qualia command, use it:
-  - `/qualia-plan {N} --gaps` if the mismatch is "plan says X but code has stubs"
-  - `/qualia-verify {N}` if the mismatch is "code says built but no verification exists"
-  - `/qualia-debug` if a specific error is the block
-  - `/qualia-map` if the plan and code have drifted far apart
-  - `/qualia-pause` if the user is overwhelmed and should step away
-```
-
-### Step 4. Close
-
-```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js end "DIAGNOSED" "{top-recommended action if it's a command, else leave blank}"
-```
-
-## Rules
-
-1. **Two isolated scans, always.** Plan view never peeks at code, code view never peeks at planning. This is what keeps the diagnosis honest — each agent sees one side of the story, and 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 (e.g., brand new repo), say "I don't have enough signal yet — here's what I'd do to gather more."
-4. **Never invent facts.** If the code-view scan didn't find something, don't say it exists. Cite files.
-5. **One recommendation primary, two backups.** Decision fatigue is the problem — give the user a lead option.
-6. **Don't re-run if state.js already knows.** If the user's confusion is purely "what's my next command", `/qualia` already handles that — gently suggest it instead of spawning agents.
-
-## When NOT to Use
-
-- User knows what they're doing and just wants the next command → `/qualia`
-- User has a specific error message → `/qualia-debug`
-- 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.