qualia-framework 5.5.0 → 5.9.0

package/docs/research/2026-05-11-deep-research.md

@@ -0,0 +1,189 @@
+# Qualia Framework — Deep Research Audit
+
+**Date:** 2026-05-11
+**Version audited:** v5.8.0 (tip `387c422`)
+**Auditors:** 4 parallel investigators (surface health, ERP integration, token economy + personalization, workflow outcomes)
+**Method:** Grounded protocol — every claim carries `file:line` citation with quoted snippet.
+
+---
+
+## Headline verdict
+
+The framework is **structurally solid** but carries three real failure modes the user was right to suspect:
+
+1. **Documentation drift is the loudest silent failure.** Three user-facing surfaces (`rules/speed.md`, `templates/help.html`, `docs/onboarding.html`) still list `/qualia-quick`, `/qualia-task`, `/qualia-design`, `/qualia-prd`, `/qualia-polish-loop` — commands removed in v5.7/v5.8. A new hire following onboarding.html immediately hits dead ends.
+2. **ERP health is better than the user feared, but one promise is a lie.** After 3 failed upload attempts the message says "will appear in ERP after retry" — there is no retry mechanism. No queue, no cron, no session-start re-try. Data sits locally until the employee manually re-runs `/qualia-report`. The retry logic that DOES exist (1s/3s/9s backoff, 401/422 permanent-fail distinction) is correct.
+3. **Always-loaded substrate is ~2× larger than the "Pocock discipline" claim implies.** CLAUDE.md is genuinely 24 lines, but the 8 rules files (~480 lines) + 33 skill descriptions (~14.7 KB) total **~10,300 tokens** on every session start. ~5,400 of those are recoverable without losing functionality.
+
+Production-readiness score (framework as a product): **77 / 100**
+
+| Dimension | Score | One-line |
+|---|---:|---|
+| Surface honesty | 6/10 | Dead refs in 3 user-facing files |
+| ERP health | 7/10 | Real retry, false retry-promise, missing idempotency |
+| Token discipline | 6/10 | Real where claimed, but ~5.4K tokens of recoverable bloat |
+| Personalization | 3/10 | 4 employees are identical clones in the framework's eyes |
+| Workflow speed | 7/10 | Road works; kickoff has redundant questions, no fast path |
+| Verifier strictness | 7/10 | Strong protocol, INSUFFICIENT EVIDENCE silently treated as PASS |
+| Test coverage | 8/10 | State machine excellently tested, workflow loop untested |
+| Hooks (safety) | 9/10 | Genuinely well-engineered, zero token tax, real enforcement |
+
+---
+
+## CRITICAL findings (zero this round)
+
+None of the four audits surfaced a CRITICAL severity issue (security breach / data loss / auth bypass / crash on happy path). The framework's safety hooks (`branch-guard`, `git-guardrails`, `migration-guard`, `pre-deploy-gate`) and state-machine locking are real defenses.
+
+This is meaningful: the user's "I think this is very fucked up" suspicion about the ERP was wrong at the data-safety level — local commit always happens before upload, retry logic is correct, API key file is mode `0600`, no shell injection.
+
+---
+
+## HIGH findings (10 — fix before next minor)
+
+### Surface honesty
+
+**H1. `rules/speed.md:50-51` lists removed `/qualia-quick` + `/qualia-task` as active.**
+`speed.md` is read by users looking for shortcuts. Users will invoke commands that don't exist.
+
+**H2. `templates/help.html:377-379` shows `/qualia-quick`, `/qualia-task`, `/qualia-design`.**
+This is what `/qualia-help` opens in the browser. It's the canonical reference page.
+
+**H3. `docs/onboarding.html:509, 524, 525, 556` shows 4 removed commands.**
+This is the file the README explicitly recommends sending to new hires.
+
+### ERP
+
+**H4. `skills/qualia-report/SKILL.md:238` — "will appear in ERP after retry" is a lie.**
+There is no retry mechanism. No background queue, no cron, no session-start drain. Either build a retry queue at `~/.claude/.erp-retry-queue.json` and drain on session-start, OR change the message to honest "Re-run /qualia-report to retry."
+
+**H5. `skills/qualia-report/SKILL.md:220-222` — no `Idempotency-Key` header sent.**
+The ERP contract documents idempotency support with a 24h replay window (`docs/erp-contract.md:42-49`). The framework ignores this. The UPSERT on `(project_id, client_report_id)` covers most cases, but retries after a response-lost-mid-flight could double-count without the explicit header.
+
+**H6. `session_duration_minutes` documented in ERP contract example but never sent.**
+`docs/erp-contract.md:93` shows it; the payload builder at `skills/qualia-report/SKILL.md:192-205` never computes it. Trivial fix: `Math.round((Date.now() - new Date(t.session_started_at)) / 60000)`.
+
+### Workflow quality
+
+**H7. `agents/verifier.md:47` — 25-call tool budget + `skills/qualia-verify/SKILL.md` doesn't block on INSUFFICIENT EVIDENCE.**
+The verifier is told "mark unchecked criteria as INSUFFICIENT EVIDENCE" when budget exhausts. The orchestrator does not grep for that string before declaring PASS. Phases with 8+ tasks can pass verification with criteria literally not checked. **This is the #1 false-pass vector.**
+
+**H8. `/qualia-new` has 15-21+ user questions before any code is written.**
+14 discovery + 1 design vibe + 1 client + 5 PRODUCT.md + N feature scoping. The PRODUCT.md questions at `skills/qualia-new/SKILL.md:163-169` overlap with discovery questions 2-5. Demos hit ~15 interactions despite the "8 questions for demos" framing.
+
+### Personalization
+
+**H9. All 4 employees (Hasan, Moayad, Rama, Sally) have identical role descriptions.**
+`bin/install.js:31-57` — every EMPLOYEE entry has the description "Developer. Feature branches only. Cannot push to main." No stack expertise, seniority, specialization. The framework cannot adapt explanation depth, task assignment, or review style per developer.
+
+**H10. `architecture.md` is always-loaded but explicitly says "Do not auto-load this on quick fixes."**
+`rules/architecture.md` is 125 lines (~1,560 tokens). It lives in `~/.claude/rules/` where Claude Code auto-loads everything. The file itself contradicts its location.
+
+---
+
+## MEDIUM findings (12 — fix this quarter)
+
+| # | Where | What |
+|---|---|---|
+| M1 | `bin/state.js:332` | Progress bar formula `(phase-1)/total_phases` — completed project shows 66%, never 100% |
+| M2 | `agents/builder.md:155`, `agents/planner.md:147`, `agents/research-synthesizer.md:91` | "likely", "probably" — hedging language the grounding protocol explicitly bans |
+| M3 | `bin/state.js:375-376` | `polished → shipped` mandatory; no skip for API-only / backend-only projects |
+| M4 | `skills/zoho-workflow/` | Completely unreferenced — orphan skill |
+| M5 | `tests/skills.test.sh` | Tests structure, not behavior — no integration test for the plan→build→verify loop |
+| M6 | `agents/plan-checker.md:83` | "Any shared file = wave conflict" forces unnecessary serialization (no read-only-overlap distinction) |
+| M7 | `agents/plan-checker.md:173-179` | Scope-reduction Rule 10 substring-matches "v1", "basic version" — false REVISE on legit plans |
+| M8 | `agents/verifier.md:315-317` + `:356-362` | Design rubric fires full 8-dim on any `.tsx` file presence — backend-heavy phases get disproportionate design scrutiny |
+| M9 | `bin/cli.js:874-888` | `erp-ping` sends synthetic payload — does not validate current schema |
+| M10 | `skills/qualia-report/SKILL.md:197` | `framework_version` reads from config snapshot at install time — stale after `npm update` |
+| M11 | `skills/qualia-new/SKILL.md:163-169` | PRODUCT.md questions duplicate discovery questions 2-5 |
+| M12 | `skills/qualia/SKILL.md:38-55` | Router has no row for "I want a one-off change outside the Road" — users must already know `/qualia-feature` exists |
+
+---
+
+## LOW findings (5)
+
+- L1. `hooks/pre-compact.js:80-81` — default `--no-verify` + `--no-gpg-sign` (configurable, documented, but silent default)
+- L2. `docs/playwright-loop-pilot-results.md:7,16,56,113` — references the renamed `skills/qualia-polish-loop/` path
+- L3. `skills/qualia-report/SKILL.md:152` — error table shows the old `set-erp-key <key>` positional syntax (CLI now requires piped)
+- L4. `bin/state.js:130` — trace probabilistic pruning (1% chance) may let `.qualia-traces/` grow unnecessarily on heavy installs
+- L5. `agents/visual-evaluator.md:91` — `likely_file` (as JSON field name, borderline)
+
+---
+
+## Cross-cutting patterns
+
+### Pattern 1: Surface drift outpaces test coverage
+
+`tests/skills.test.sh` validates that every SKILL.md has the right frontmatter. It does NOT validate that command references inside SKILL.md, rules/, docs/, templates/ point to skills that still exist. Three v5.7/v5.8 removals slipped through because the test surface is structural, not referential.
+
+**Fix:** Add `tests/refs.test.sh` that greps every `.md` and `.html` for `/qualia-{name}` and asserts each name has a matching `skills/qualia-{name}/SKILL.md`.
+
+### Pattern 2: The framework is more disciplined than its tooling enforces
+
+CLAUDE.md is genuinely lean. Design substrate was correctly moved off the always-loaded path. Hooks enforce deterministically. But:
+
+- `rules/architecture.md` lives where it auto-loads despite its own warning
+- Skill descriptions accumulate flavor text ("Karpathy-style", "v5.3 from Matt Pocock's...") on top of trigger phrases — every change invalidates the cache prefix
+- 8 rules files always-load when 3 are sufficient for most sessions
+
+**Fix:** A `tests/budget.test.sh` that asserts total always-loaded substrate stays under ~6,000 tokens.
+
+### Pattern 3: The verifier knows what to check but can't always afford to check it
+
+The 3-level verification (Truths / Artifacts / Wiring) is the right abstraction. The 25-call budget makes it un-affordable on phases with 8+ tasks. INSUFFICIENT EVIDENCE is the escape hatch, but the orchestrator doesn't punish it. So the verifier silently approves under-verified phases.
+
+**Fix:** Budget = `max(25, tasks * 5)`. AND: any INSUFFICIENT EVIDENCE in the verification file → verdict downgraded to FAIL.
+
+### Pattern 4: Personalization is structurally absent
+
+There are 4 distinct humans (Hasan, Moayad, Rama, Sally) who get an identical one-sentence description. The daily-log, knowledge layer, learned-patterns, and commit history all contain per-user signal that is collected and never read for personalization.
+
+**Fix:** Per-employee profile file under `~/.claude/team/{code}.md`, injected into CLAUDE.md template at install time. Auto-derived from daily logs via a `/qualia-flush` extension.
+
+---
+
+## Top 10 fixes ranked by ROI
+
+1. **Find-and-replace the 6 dead command references in `speed.md`, `help.html`, `onboarding.html`** — 15 min. Eliminates every user-facing dead end.
+2. **Add INSUFFICIENT EVIDENCE blocker to `qualia-verify`** — 20 min. Eliminates the #1 false-pass vector.
+3. **Stop lying about retry: either build the queue or change the message** — 30 min for the message change, ~3 hours for the queue.
+4. **Send `Idempotency-Key` + `session_duration_minutes` in ERP payload** — 20 min. Completes the documented contract.
+5. **Move `architecture.md` to `~/.claude/qualia-substrate/` (lazy-load)** — 10 min. Saves ~1,560 tokens per session.
+6. **Trim skill descriptions to trigger-phrases-only** — 1 hour. Saves ~1,500 tokens per session + improves cache stability.
+7. **Per-employee profile files (`team/{code}.md`)** — 2 hours. Transforms personalization from 0 to material.
+8. **Scale verifier budget to `max(25, tasks*5)`** — 5 min. Eliminates INSUFFICIENT EVIDENCE on large phases.
+9. **Merge PRODUCT.md questions into the discovery interview** — 30 min. Cuts ~3 questions from every kickoff.
+10. **Add `tests/refs.test.sh`** — 45 min. Prevents the next surface-drift incident.
+
+**Total effort for all 10:** ~8-10 hours.
+**Effort-weighted impact:** removes every found false-pass vector, every documented dead-link, ~3K of recoverable tokens, the framework's biggest UX papercut (personalization), and the largest invisible quality risk (INSUFFICIENT EVIDENCE silently passing).
+
+---
+
+## What the framework does WELL (honest acknowledgement)
+
+These are not patronizing — they came up across all four audits.
+
+1. **State machine** (`bin/state.js`). 57 behavioral tests. Atomic dual-file writes. File-based locking with stale detection. Crash-recovery journaling. Gap-cycle circuit breaker with configurable limit. Schema validation + repair. This is real engineering.
+2. **Hook architecture.** Pure Node.js (Windows-safe). Zero model-token tax (deterministic enforcement, not instructional). Real protections: service_role leak scan, force-push-to-main block (role-aware), migration safety, Vercel account guard, env-empty guard.
+3. **Verifier abstraction** (Truths / Artifacts / Wiring). Most AI coding tools check "did the task run." The Qualia verifier checks "is the artifact substantive, is it imported, is it called." The stub-detection patterns are operational learning, not theory.
+4. **Polish-loop kill-switch.** Fingerprint regression detection + budget cap. Real engineering against the known infinite-loop failure mode of vision-model feedback loops.
+5. **ERP security hardening.** Native `https.request` instead of curl (no bearer in `/proc/cmdline`). API key mode `0600`. Refuses positional CLI args. Env-var passing in payload builder (no shell injection). Atomic tmp+rename writes.
+
+---
+
+## Resources & references
+
+- All findings cite specific files. Original investigator outputs from this audit are not committed (held in conversation context).
+- Grounding protocol: `/home/qualia-new/.claude/rules/grounding.md`
+- Severity criteria: same file.
+- Pocock instruction-budget pattern: referenced in README:8.
+- ERP contract spec: `docs/erp-contract.md` (this file exists and was used by the ERP-integration audit).
+
+---
+
+## Open questions for the user
+
+1. **The retry-queue approach for ERP** — would you prefer (a) an honest message change ("re-run to retry"), (b) a queue file drained on session-start, or (c) a cron job? Each has different operational characteristics.
+2. **Personalization depth** — willing to spend an afternoon writing 4 profile files for Hasan/Moayad/Rama/Sally? Or want this auto-derived from daily logs over time?
+3. **Token cuts vs cache stability** — some of the cuts (e.g. trimming skill descriptions) will invalidate prompt caches for one cycle. Worth it once, or keep stable?
+4. **The 14-question discovery interview** — keep depth at the kickoff cost, or shave 4-5 questions and accept slightly fuzzier project framing?

package/guide.md

@@ -1,9 +1,9 @@
-# Qualia Developer Guide (v5.3)
+# Qualia Developer Guide (v5.8)
 
 > Follow the road. Type the commands. The framework handles the rest.
 > `--auto` chains the whole road end-to-end with only two human checkpoints per project.
 
-**v5.3 ships three Matt-Pocock gap closures:** `/qualia-prd` (synthesize conversation → durable spec), `/qualia-hook-gen` (CLAUDE.md instruction → deterministic hook), `/qualia-optimize --deepen` Step 5b (3 parallel-interface design variants for refactor RFCs). Plus the visual-polish loop (`/qualia-polish-loop`) from v5.1 with reduced-motion + multi-route flags from v5.2.
+**v5.8 cleans up the command surface:** `/qualia-polish-loop` is now `/qualia-polish --loop` (one flag instead of two skills). `/qualia-quick`, `/qualia-task`, and `/qualia-prd` are removed after their v5.7 deprecation window; use `/qualia-feature` for single-feature work and `/qualia-discuss` in PROJECT MODE for kickoff capture. Skill count goes from 35 to 32.
 
 ## The Road
 
@@ -52,14 +52,13 @@ Append `--auto` to `/qualia-new` and the framework chains every step:
 | Starting | `/qualia-new` | Set up project with full journey (all milestones → Handoff) |
 | Starting (auto) | `/qualia-new --auto` | Same + chain through building automatically |
 | Brownfield | `/qualia-map` | Map an existing codebase BEFORE `/qualia-new` |
-| Mid-project spec | `/qualia-prd` | Synthesize the current conversation into a durable feature spec (v5.3+) |
 | Building | `/qualia-plan` | Plan the current phase |
 | | `/qualia-build` | Build it (parallel tasks) |
 | | `/qualia-verify` | Check it actually works |
 | Milestone | `/qualia-milestone` | Close current, open next from JOURNEY.md |
-| Quick fix | `/qualia-quick` | Skip planning, just do it |
-| Finishing | `/qualia-polish` | Design and UX pass (scope-adaptive: component / route / app / redesign / critique / quick) |
-| | `/qualia-polish-loop` | Autonomous visual-polish loop — screenshot → vision-eval → fix → repeat (v5.1+) |
+| Single feature | `/qualia-feature` | Auto-scoped: inline for trivia, fresh spawn for 1-5 files |
+| Finishing | `/qualia-polish` | Design and UX pass (scope-adaptive: component / route / app / redesign / critique / quick / loop) |
+| | `/qualia-polish --loop` | Autonomous visual-polish loop: screenshot, vision-eval, fix, repeat |
 | | `/qualia-ship` | Deploy to production |
 | | `/qualia-handoff` | Deliver to client (4 mandatory deliverables) |
 | Reporting | `/qualia-report` | Log what you did (mandatory before clock-out) |

package/hooks/session-start.js

@@ -26,6 +26,8 @@ const STATE_FILE = path.join(".planning", "STATE.md");
 const CONTINUE_HERE = ".continue-here.md";
 const NOTIF_FILE = path.join(HOME, ".claude", ".qualia-update-available.json");
 const HEALTH_FILE = path.join(HOME, ".claude", ".qualia-install-health.json");
+const ERP_RETRY = path.join(HOME, ".claude", "bin", "erp-retry.js");
+const ERP_QUEUE = path.join(HOME, ".claude", ".erp-retry-queue.json");
 
 // Critical files referenced by skills via @-import. If any are missing, skills
 // silently get empty context and produce ungrounded output. We spot-check these
@@ -115,6 +117,21 @@ function fallbackText() {
   }
 }
 
+function maybeDrainErpQueue() {
+  // Fire-and-forget drain of any reports stranded from a prior /qualia-report
+  // upload failure. Cheap fast-path: only spawn if the queue file exists and
+  // erp-retry.js is installed. Quiet mode + small max so we never block the
+  // session-start critical path. The script itself exits 0 even on internal
+  // errors — see erp-retry.js's CLI tail.
+  try {
+    if (!fs.existsSync(ERP_QUEUE) || !fs.existsSync(ERP_RETRY)) return;
+    spawnSync(process.execPath, [ERP_RETRY, "drain", "--quiet", "--max=5", "--timeout=2500"], {
+      stdio: "ignore",
+      timeout: 8000,
+    });
+  } catch {}
+}
+
 function maybeRenderUpdateBanner() {
   // EMPLOYEE-only sticky banner. auto-update.js writes NOTIF_FILE when a new
   // version is detected; we render it every session until the user actually
@@ -144,6 +161,7 @@ function renderHealthWarning(missing) {
 
 try {
   maybeRenderUpdateBanner();
+  maybeDrainErpQueue();
 
   const healthMissing = checkInstallHealth();
   if (healthMissing) renderHealthWarning(healthMissing);
@@ -173,7 +191,7 @@ try {
     console.log(`  ${DIM}Start here:${RESET}`);
     console.log(`    ${TEAL}/qualia-new${RESET}    ${DIM}Set up a new project${RESET}`);
     console.log(`    ${TEAL}/qualia${RESET}        ${DIM}What should I do next?${RESET}`);
-    console.log(`    ${TEAL}/qualia-quick${RESET}  ${DIM}Quick fix (skip planning)${RESET}`);
+    console.log(`    ${TEAL}/qualia-feature${RESET} ${DIM}Single feature (auto-scoped)${RESET}`);
     console.log("");
   }
 } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "5.5.0",
+  "version": "5.9.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -31,7 +31,8 @@
     "test:skills": "bash tests/skills.test.sh",
     "test:slop-detect": "bash tests/slop-detect.test.sh",
     "test:statusline": "bash tests/statusline.test.sh",
-    "test:shell": "bash tests/statusline.test.sh && bash tests/state.test.sh && bash tests/hooks.test.sh && bash tests/bin.test.sh && bash tests/lib.test.sh && bash tests/skills.test.sh && bash tests/slop-detect.test.sh"
+    "test:refs": "bash tests/refs.test.sh",
+    "test:shell": "bash tests/statusline.test.sh && bash tests/state.test.sh && bash tests/hooks.test.sh && bash tests/bin.test.sh && bash tests/lib.test.sh && bash tests/skills.test.sh && bash tests/refs.test.sh && bash tests/slop-detect.test.sh"
   },
   "files": [
     "bin/",

package/rules/speed.md

@@ -47,8 +47,7 @@ The pattern: **on-demand by default; always-on only when the data is irreducibly
 
 When a Qualia command exists for the situation, use it — don't reinvent:
 - `/qualia` — what's my next step?
-- `/qualia-quick` — small inline fix, no plan, no spawn
-- `/qualia-task` — single focused task, fresh builder spawn, atomic commit
+- `/qualia-feature` — single feature, auto-scoped: inline for trivia, fresh builder spawn for 1-5 file features
 - `/qualia-ship` — full deploy pipeline (quality gates → commit → deploy → verify)
 - `/qualia-review` — production audit
 - `/qualia-pause` — save context before clearing the conversation

package/skills/qualia-discuss/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-discuss
-description: "Aggressive alignment interview before planning a phase — asks ONE question at a time, proposes a recommended answer with each, walks every branch of the decision tree until resolved. Updates .planning/CONTEXT.md inline as terms crystallize and writes ADRs for hard-to-reverse decisions. Output: .planning/phase-{N}-context.md (locked input the planner honors). Use BEFORE /qualia-plan for high-stakes phases (regulatory, auth, payments, multi-tenant, architectural forks), or when the user says 'discuss', 'grill me', 'stress test this plan', 'wait let's think about this one', 'I'm not sure how to approach this'."
+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'."
 allowed-tools:
   - Bash
   - Read
@@ -11,24 +11,124 @@ allowed-tools:
   - AskUserQuestion
 ---
 
-# /qualia-discuss — Alignment Interview Before Planning
+# /qualia-discuss — Alignment Interview
+
+Two modes. The skill picks one based on whether an arg is passed.
+
+| Arg | Mode | When | Output |
+|-----|------|------|--------|
+| (none) | **PROJECT MODE** | Kickoff, before `/qualia-new`. Non-technical, audience-facing. | `.planning/project-discovery.md` |
+| `N` (e.g. `2`) | **PHASE MODE** | Before `/qualia-plan N`. Technical, aggressive grilling. | `.planning/phase-{N}-context.md` |
+
+## Mode routing
+
+```bash
+if [ -z "$1" ] || ! [[ "$1" =~ ^[0-9]+$ ]]; then
+  MODE="project"
+else
+  MODE="phase"
+  PHASE_N="$1"
+fi
+```
+
+If `MODE=project` → jump to **PROJECT MODE** section below.
+If `MODE=phase` → jump to **PHASE MODE** section below.
+
+---
+
+# PROJECT MODE — Kickoff Interview (no args)
+
+The non-technical conversation that runs at the very start of `/qualia-new`, BEFORE any roadmapping or research. Captures what the client wants, who it's for, brand voice, and constraints — in the client's own words.
+
+Hard rule: **never go technical here.** No "Should we use Supabase or Postgres?". The technical decisions happen in PHASE MODE, per phase. This mode is for the human shape of the project.
+
+## When PROJECT MODE runs
+
+- Triggered automatically by `/qualia-new` after Step 0 banner, BEFORE journey generation.
+- Or invoked manually (e.g. on a brownfield project that already has code but no discovery doc).
+
+## Process — PROJECT MODE
+
+### P1. Detect project type (or accept it from `/qualia-new`)
+
+If `/qualia-new` already asked the Demo vs Full gate, it passes the type in as `PROJECT_TYPE=demo` or `PROJECT_TYPE=full` via env or arg. Otherwise ask first:
+
+- header: "Project shape"
+- question: "Is this a demo (single shippable milestone, sales conversation, ~1 to 2 weeks) or a full project (multi-milestone arc to Handoff)?"
+- options: ["Demo", "Full project"]
+
+This is the only fork. Demo runs §1-§8 of the discovery template. Full project runs all 14 questions.
+
+### P2. Banner and open
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner discuss-project
+```
+
+Say: **"Eight quick questions for the demo path"** or **"Fourteen questions to shape the full project — we'll move fast"** depending on type.
+
+### P3. One question at a time, copy from `templates/project-discovery.md`
+
+For each question §1..§8 (demo) or §1..§14 (full), ask in plain language. Format:
+
+```
+**Question {N}/{total}:** {question text from template}
+
+({one-line clarifier showing the kind of answer that helps)
+```
+
+NO "my recommendation" line in PROJECT MODE — this is open discovery, not technical grilling. Wait for the user's answer. Don't paraphrase back; capture verbatim. If the answer is too thin, ask one follow-up max, then move on.
+
+Allowed `[Enter]` defaults exist on §2, §3, §5 only (inferred from project type). All other questions require an answer.
+
+### P4. Write `.planning/project-discovery.md`
+
+Fill the template at `~/.claude/qualia-templates/project-discovery.md` with the user's verbatim answers. Set frontmatter `project_type` and `discovered_at`.
+
+### P5. Hand back to `/qualia-new`
+
+```bash
+git add .planning/project-discovery.md
+git commit -m "docs: project discovery interview ($PROJECT_TYPE)"
+node ~/.claude/bin/qualia-ui.js ok "Discovery captured — back to /qualia-new"
+```
+
+If invoked standalone (not from `/qualia-new`), end with:
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "DISCOVERY CAPTURED" "/qualia-new"
+```
+
+If invoked inline by `/qualia-new`, return control silently — `/qualia-new` continues from Step 2.
+
+## Rules — PROJECT MODE
+
+1. **Never technical.** No stack questions, no architecture forks. Those are PHASE MODE.
+2. **Verbatim capture.** Don't translate the client's words into framework-speak. The client's exact phrasing is the input to PRODUCT.md voice and CONTEXT.md glossary.
+3. **One question, one answer, move on.** No batching. No drilling deeper than one follow-up.
+4. **Demo stops at §8.** Don't ask demo clients milestone-arc questions — they don't have an arc yet.
+5. **Anti-references are required.** If the user can't name three sites this should NOT look like, the design will end up generic. Push back once, then capture whatever they give you.
+
+---
+
+# PHASE MODE — Pre-Plan Grilling (`/qualia-discuss N`)
 
 Surface and lock the decisions, trade-offs, and constraints that must inform a phase plan. Output: `.planning/phase-{N}-context.md` (locked input). Side effects: `.planning/CONTEXT.md` gains new terms; `.planning/decisions/` may gain ADRs.
 
-## When to use
+## When PHASE MODE runs
 - Regulated domains (legal, medical, financial) where wrong choices have legal cost
 - Phases with architectural forks ("auth via middleware or RLS?")
 - Phases with external dependencies you want to lock first
 - User says "wait, let's think about this one"
 
-## The four grilling rules
+## The four grilling rules (PHASE MODE)
 
 1. **One question at a time.** Wait for the answer before asking the next. Never batch.
 2. **Propose your recommended answer first.** Format every question as `Question / Recommendation / Trade-offs`. The user accepts, edits, or rejects — way faster than open interview.
 3. **If the codebase can answer, explore instead of asking.** Don't make the user say what `git grep` could tell you.
 4. **Walk every branch.** When the user picks A over B, the next question is the one that A makes load-bearing. Resolve dependencies one-by-one until the tree is fully traversed.
 
-## Process
+## Process — PHASE MODE
 
 ### 1. Load substrate
 
@@ -108,7 +208,7 @@ git commit -m "docs(phase-{N}): lock context, glossary terms, ADRs"
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} CONTEXT LOCKED" "/qualia-plan {N}"
 ```
 
-## Rules
+## Rules — PHASE MODE
 
 1. **One session, one phase.** Don't discuss phases 1 and 2 in the same invocation.
 2. **Locked decisions are NON-NEGOTIABLE.** The planner honors them exactly. Don't lock what you're unsure of — defer it instead.