qualia-framework 5.4.0 → 5.8.0

package/package.json

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

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
 
@@ -67,10 +167,24 @@ Wait for response. Then:
 - Write an ADR in `.planning/decisions/ADR-{NNNN}-{slug}.md` ONLY when the decision is hard-to-reverse, surprising-without-context, AND involves real trade-offs (use the template — keep it scarce)
 - Drill deeper if the answer opens new branches
 
-### 4. Build the locked-decisions list
+### 4. Build the locked-decisions list (with IDs — machine-parseable downstream)
+
+For each resolved decision, capture as a row with a stable ID `D-NN` (zero-padded, sequential within the phase). The planner's Decision Coverage Audit checks every `D-NN` is implemented; the plan-checker BLOCKS if any is missing.
+
+**Locked Decision row format:**
+
+| ID | Decision | Rationale | Source |
+|----|----------|-----------|--------|
+| D-01 | Use Supabase RLS for authorization, not middleware | Compliance requires database-level checks | discuss session 2026-05-09 |
+| D-02 | Store session tokens server-side, not in JWT | OWASP guidance + revocation requirement | ADR-0007 |
+
+Also track:
+- **Discretion items** — planner decides based on best practice (no IDs needed).
+- **Deferred ideas** — explicitly NOT this phase. The plan-checker will REVISE if any of these appears in a task.
+- **Risk flags** — watch during build (no IDs).
+- **Open questions** — still unresolved. Cannot lock until resolved.
 
-For each resolved decision, capture: choice (what) / rationale (why) / source (who/when).
-Also track: **Discretion items** (planner decides) / **Deferred ideas** (NOT this phase) / **Risk flags** (watch during build) / **Open questions** (still unresolved).
+When you reference a decision later (in commit messages, task Why fields, ADRs), use its ID — `D-03` is shorter than the full decision text and cross-checkable.
 
 ### 5. Decision gate
 
@@ -94,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.

package/skills/qualia-feature/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: qualia-feature
+description: "Auto-scoped single feature build. Picks inline (≤1 trivial file, no spawn) or fresh builder spawn (1-5 logic files, atomic commit) automatically from the task description. Refuses and routes to /qualia-plan for 5+ files or full phases. Replaces /qualia-quick and /qualia-task. Flags: --force-spawn forces a builder, --force-inline forces inline. Trigger phrases: 'build this one thing', 'add a component', 'implement this feature', 'quick fix', 'small change', 'tweak', 'hot fix', 'one-line fix', 'typo', 'config tweak', 'qualia-feature'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+  - AskUserQuestion
+---
+
+# /qualia-feature — Auto-scoped Single Feature
+
+One command for everything between a typo and a phase. Auto-detects scope from the task description and picks the right execution path. No more guessing whether to use `/qualia-quick` or `/qualia-task`.
+
+## Usage
+
+`/qualia-feature` — describe interactively
+`/qualia-feature {description}` — run with description directly
+`/qualia-feature --force-spawn {description}` — force a fresh builder spawn (even if auto would inline)
+`/qualia-feature --force-inline {description}` — force inline path (even if auto would spawn)
+
+## When to use
+
+- One feature outside a planned phase
+- A bug fix, typo, config tweak, or one-line change
+- A 1-5 file feature, component, API route, or integration
+- A refactor of a single module
+
+## When NOT to use
+
+- 5+ files or multiple subsystems touched → `/qualia-plan`
+- Part of a planned phase → `/qualia-build`
+- Investigating a symptom you can't name yet → `/qualia-debug`
+- Optimization or polish pass → `/qualia-optimize` or `/qualia-polish`
+
+## Process
+
+### 1. Capture description
+
+If invoked without args, ask: **"What do you want to build?"**
+
+Wait for free-text answer. Don't paraphrase back. Capture the user's exact phrasing — it feeds both the auto-scope classifier and the eventual commit message.
+
+### 2. Auto-detect scope
+
+Classify the description into one of three buckets:
+
+| Bucket | Heuristic | Path |
+|--------|-----------|------|
+| **inline** | Typo, comment edit, 1-line config change, single-word rename, dead-code removal, copy edit, link fix, version bump, single emoji/icon swap | Direct work, no spawn |
+| **spawn** | Add a component, add an API route, add a small migration + UI, implement a single feature, fix a non-trivial bug, refactor a module under 5 files | Fresh builder spawn |
+| **refuse** | "Build the dashboard", "implement payments", "ship the auth system", "add a checkout flow", any description that names a multi-step workflow or 5+ subsystems | Refuse, route to `/qualia-plan` |
+
+**Inline signals** (any one is sufficient):
+- "fix typo", "fix the comment", "rename X to Y", "remove unused", "update copy", "change the link", "bump version"
+- Description fits in one short sentence and names one specific micro-change
+- The action is reversible by a single `git revert`
+
+**Spawn signals** (any one is sufficient):
+- "add a", "implement", "build", "create" + a single noun (component, route, page, table, form, modal, hook, util, migration)
+- Description names a single feature with multiple touch points (e.g. "add a feedback form" → migration + API + UI = 3-4 files, but still one cohesive thing)
+- The work needs a fresh context to avoid contaminating the current conversation
+
+**Refuse signals** (any one is sufficient):
+- "build the X system", "implement the entire Y", "add complete Z support"
+- Description names a multi-milestone capability (auth, payments, search, admin panel) without a tight slice
+- Estimated touch ≥ 5 files OR ≥ 1 day
+
+### 3. Announce the route + escape hatch
+
+Show the user what was detected. Always offer the escape hatch:
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner feature
+node ~/.claude/bin/qualia-ui.js info "Detected scope: {inline|spawn|refuse}"
+node ~/.claude/bin/qualia-ui.js info "Reason: {one-line rationale}"
+```
+
+Then:
+
+- header: "Scope detected"
+- question: "Auto-scope says {bucket}. Proceed, or override?"
+- options:
+  - "Proceed with {bucket}"
+  - "Force inline" (only shown if bucket != inline)
+  - "Force spawn" (only shown if bucket != spawn)
+  - "Route to /qualia-plan" (only shown if bucket != refuse)
+  - "Re-describe"
+
+If `--force-spawn` or `--force-inline` was passed on the command line, skip this gate entirely and execute the forced path.
+
+### 4. Execute the inline path
+
+For inline scope:
+
+1. Read the file(s) that need to change (one read per file, no spawning).
+2. Make the edit directly using Edit/Write.
+3. Run `npx tsc --noEmit` if TypeScript and the change touches typed code; skip otherwise.
+4. Atomic commit with a clear conventional-commit message:
+
+```bash
+git add {specific files}
+git commit -m "fix: {description}"
+```
+
+5. Record in state:
+
+```bash
+node ~/.claude/bin/state.js transition --to note --notes "{brief description}" --tasks-done 1
+```
+
+6. End with:
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "FEATURE SHIPPED (inline)"
+```
+
+### 5. Execute the spawn path
+
+For spawn scope:
+
+1. Build a quick task spec (don't write to a file, just confirm with user):
+
+```bash
+node ~/.claude/bin/qualia-ui.js info "What: {what to build}"
+node ~/.claude/bin/qualia-ui.js info "Files: {files to create/modify, comma list}"
+node ~/.claude/bin/qualia-ui.js info "Done: {observable acceptance criteria, 1-3 bullets}"
+```
+
+Ask: **"Good to build?"** Wait for confirmation.
+
+2. Spawn the builder:
+
+```
+Agent(subagent_type="qualia-builder", description="Feature: {short title}")
+  prompt: |
+    Read your role: @~/.claude/agents/builder.md
+
+    <task>
+    {task description verbatim from user}
+    </task>
+
+    <files>
+    {files to create/modify}
+    </files>
+
+    <acceptance_criteria>
+    {1-3 observable bullets}
+    </acceptance_criteria>
+
+    <context>
+    Read .planning/PROJECT.md if it exists.
+    Read .planning/CONTEXT.md if it exists (domain glossary).
+    Follow rules/security.md, rules/frontend.md, rules/deployment.md as applicable.
+    Atomic commit. Run npx tsc --noEmit before commit.
+    </context>
+```
+
+3. After the builder returns, verify:
+   - `npx tsc --noEmit` exits 0 (rerun the builder up to 2x if it failed self-verify, per the v5.5.0 auto-heal pattern).
+   - Quick smoke test if applicable.
+   - Confirm the commit was made: `git log --oneline -1` shows the feature.
+
+4. Report:
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "Feature: {description}"
+node ~/.claude/bin/qualia-ui.js ok "Files: {files changed}"
+node ~/.claude/bin/qualia-ui.js ok "Commit: {commit hash}"
+node ~/.claude/bin/qualia-ui.js end "FEATURE SHIPPED (spawn)"
+```
+
+5. Record in state:
+
+```bash
+node ~/.claude/bin/state.js transition --to note --notes "{description}" --tasks-done 1
+```
+
+### 6. Execute the refuse path
+
+For refuse scope, do NOT build. Explain why and route:
+
+```bash
+node ~/.claude/bin/qualia-ui.js warn "This is too big for /qualia-feature (5+ files or multi-step workflow)."
+node ~/.claude/bin/qualia-ui.js info "Reason: {one-line — e.g. 'description names the entire auth system, not a slice'}"
+node ~/.claude/bin/qualia-ui.js end "ROUTED" "/qualia-plan"
+```
+
+If the user is sure it's small and the classifier got it wrong, they can re-invoke with `--force-spawn`.
+
+## Auto-scope examples
+
+| Description | Detected | Why |
+|-------------|----------|-----|
+| "fix the typo in the hero copy" | inline | typo + 1 file |
+| "rename `userId` to `user_id` in auth.ts" | inline | rename in 1 file |
+| "bump next from 16.0.3 to 16.0.4" | inline | version bump, 1 file |
+| "add a Feedback button that opens a modal" | spawn | single feature, 2-4 files |
+| "add a GET /api/health route returning ok" | spawn | 1 route, but worth a fresh context for test pass |
+| "implement Stripe subscription checkout" | refuse | multi-file + webhooks + admin = phase |
+| "build the dashboard" | refuse | names a multi-page surface |
+| "add the admin user-management page" | refuse | usually 5+ files (table, modals, API, RLS, types) |
+
+## Rules
+
+1. **Auto-scope is confident by default, with two escape hatches.** Trust the classifier; use `--force-spawn` or `--force-inline` when it guesses wrong. Don't waste a question on "which path?" — propose and let the user override.
+2. **Inline is genuinely fresh-context-free.** No subagent spawn for inline work — the current Claude does it directly. That's the whole speed advantage over `/qualia-task`.
+3. **Spawn means atomic.** One feature, one commit, one acceptance criteria block. No grab-bag commits that touch four unrelated things.
+4. **Refuse means refuse.** When a description is phase-sized, route to `/qualia-plan`, don't try to fit it in. The auto-classifier is the gate that protects the work from sprawling.
+5. **STATE.md via state.js only.** Never edit STATE.md or tracking.json by hand. Both paths record through `state.js transition`.
+6. **Follow rules/* on every path.** Security, frontend, deployment rules apply equally to inline and spawn. Read-before-write is non-negotiable.

package/skills/qualia-milestone/SKILL.md

@@ -38,6 +38,77 @@ node ~/.claude/bin/state.js check
 
 If either fires (without `--force`), stop and show the error. The user must verify remaining phases first (or add `--force` for explicit bypass on a preview/demo milestone).
 
+### 1b. Demo-Extension Branch (v5.6)
+
+Detect if this is a demo project closing its only milestone:
+
+```bash
+PROJECT_TYPE=$(grep -E "^project_type:" .planning/PROJECT.md | head -1 | awk '{print $2}')
+MILESTONE_COUNT=$(grep -cE "^## Milestone " .planning/JOURNEY.md 2>/dev/null || echo 0)
+```
+
+If `PROJECT_TYPE=demo` AND `MILESTONE_COUNT=1`, the demo's one milestone is closing — there is no "next milestone" in the file. Ask the conversion question:
+
+- header: "Demo shipped — what next?"
+- question: "The demo milestone is done. Did the client sign? If yes, extend this into a full project (regenerate JOURNEY.md as a multi-milestone arc to Handoff). If no, this project closes here."
+- options:
+  - "Client signed — extend to full project"
+  - "Demo only — close here, project is done"
+  - "Pause" — don't close yet, decide later
+
+**If "Client signed — extend to full project":**
+
+1. Update `.planning/PROJECT.md` frontmatter: `project_type: full`.
+2. Run a brief discovery top-up — invoke `/qualia-discuss` in PROJECT MODE, but only ask §9-§14 (the full-project-only questions). This adds the milestone arc, compliance, integrations, content ownership, handoff team, and budget shape.
+3. Spawn the roadmapper in `extend-to-full` mode (see prompt below). It reads the existing single milestone (now M1), the updated discovery, and produces a full JOURNEY.md with M2..M{N-1} sketches plus the Handoff milestone.
+4. Then proceed with the standard close-milestone flow (Steps 2-9) — M1 closes, M2 opens, the user is asked to continue.
+
+Roadmapper prompt for the extension:
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/roadmapper.md
+
+<mode>extend-demo-to-full</mode>
+<existing_journey>.planning/JOURNEY.md</existing_journey>
+<discovery>.planning/project-discovery.md</discovery>
+
+<task>
+The existing JOURNEY.md has 1 milestone (the demo, now M1 and shipped). Extend it
+into a 2-5 milestone arc to Handoff:
+
+- Keep M1 exactly as-is (it shipped).
+- Add M2..M{N-1} based on §9 of project-discovery.md (the milestone-arc question
+  the user answered when converting from demo).
+- Append a Handoff milestone (fixed 4 phases: Polish, Content + SEO, Final QA,
+  Handoff).
+- Update REQUIREMENTS.md to add REQ-IDs for the new milestones.
+- Do NOT regenerate ROADMAP.md here — that happens in Step 7 of /qualia-milestone
+  when M2 opens.
+
+Mark M2..M{N-1} as sketched, not fully detailed. The user gets full detail per
+milestone when /qualia-milestone opens each one.
+</task>
+", subagent_type=\"qualia-roadmapper\", description=\"Extend demo to full project\")
+```
+
+**If "Demo only — close here":** treat the demo as a shipped-and-done project. Skip Steps 2-9 of the normal flow. Just run:
+
+```bash
+node ~/.claude/bin/state.js close-milestone --force
+node ~/.claude/bin/qualia-ui.js end "DEMO SHIPPED" "/qualia-report"
+```
+
+In `--auto` mode, inline-invoke `/qualia-report` and stop.
+
+**If "Pause":** stop, show:
+
+```bash
+node ~/.claude/bin/qualia-ui.js info "Demo milestone left open. Run /qualia-milestone again when you decide."
+```
+
+If the demo branch did NOT fire (full project, or demo with multiple milestones already after extension), continue to Step 2.
+
 ### 2. Banner + Confirm
 
 ```bash
@@ -206,4 +277,5 @@ node ~/.claude/bin/qualia-ui.js end "M{N} CLOSED · M{N+1} OPEN" "/qualia-plan 1
 3. **Archive, don't delete.** Old phase work stays accessible via `.planning/archive/`.
 4. **New milestone = fresh phase numbering.** First phase of the new milestone is Phase 1, not Phase {N+1}.
 5. **ERP sync aware.** tracking.json milestones[] gets a summary entry on close — the ERP reads this to render the tree.
-6. **Handoff is the final milestone.** If the current milestone IS Handoff, there is no "next" — route to `/qualia-report` and the project is done.
+6. **Handoff is the final milestone (full projects).** If the current milestone IS Handoff, there is no "next" — route to `/qualia-report` and the project is done.
+7. **Demo closes via the demo-extension branch (Step 1b).** A demo's single milestone closing triggers the "client signed?" question. The framework never silently auto-extends a demo without asking — the conversion is a real business decision.

package/skills/qualia-new/SKILL.md

@@ -58,27 +58,41 @@ test -d .git && echo "HAS_GIT"
 test -f .planning/codebase/README.md && echo "ALREADY_MAPPED"
 ```
 
-If existing code is detected AND not already mapped, ask the user whether to run `/qualia-map` inline first. If yes, invoke the `qualia-map` skill inline, wait for completion, then continue to Step 1.
+If existing code is detected AND not already mapped, ask the user whether to run `/qualia-map` inline first. If yes, invoke the `qualia-map` skill inline, wait for completion, then continue to Step 0.6.
 
-### Step 1. Deep Questioning
+### Step 0.6. Project Type Gate (Demo vs Full)
 
-Load the questioning methodology:
+The single most important fork in the workflow. Demo and Full produce different journeys, different research depth, different milestone counts.
 
-```bash
-cat ~/.claude/qualia-references/questioning.md 2>/dev/null
-```
+- header: "Project shape"
+- question: "Is this a demo (single shippable milestone, sales conversation) or a full project (multi-milestone arc to Handoff)?"
+- options:
+  - "Demo" — one shippable milestone, real backend, no mocks. Built to win a client conversation, extensible via `/qualia-milestone` if they sign.
+  - "Full project" — the full multi-milestone arc to Handoff. 2-5 milestones planned upfront.
+
+Store the answer as `PROJECT_TYPE=demo` or `PROJECT_TYPE=full`. It drives Steps 1, 8, and 10.
 
-Follow the thread. Challenge vagueness. Make abstract concrete. Check the 4-item mental checklist (what, why, who, done).
+**Demo design philosophy is non-negotiable:** real backend always, DESIGN.md mandatory, slop-detect hard-block. Speed comes from skipping multi-milestone planning, NEVER from skipping design quality or mocking the backend.
 
-Use `AskUserQuestion` for forks with 2-4 concrete interpretations. Use free text when you want them to think freely.
+### Step 1. Mandatory Discovery Interview (PROJECT MODE)
 
-**Decision gate** — when you could write a clear PROJECT.md:
+Invoke `/qualia-discuss` inline in PROJECT MODE — non-technical kickoff interview. 8 questions for demo, 14 for full project. Pass `PROJECT_TYPE` so the discuss skill skips the type question.
+
+This step REPLACES the old free-form "deep questioning" loop. The discuss skill captures answers verbatim into `.planning/project-discovery.md`, which seeds PROJECT.md, PRODUCT.md, CONTEXT.md, and (for full projects) JOURNEY.md milestone names.
+
+```bash
+# Inline-invoke qualia-discuss in PROJECT MODE
+# (no phase number arg = PROJECT MODE; PROJECT_TYPE env tells it which question set)
+PROJECT_TYPE=$PROJECT_TYPE qualia-discuss
+```
+
+After the interview returns, `.planning/project-discovery.md` exists with the user's answers. Read it. Confirm understanding:
 
 - header: "Ready?"
-- question: "I understand what you're building. Create PROJECT.md and move forward?"
-- options: ["Create PROJECT.md", "Keep exploring"]
+- question: "I have what I need to write PROJECT.md and move forward. Continue?"
+- options: ["Continue", "More questions"]
 
-Loop until "Create PROJECT.md".
+If "More questions": re-invoke `/qualia-discuss` for additional rounds. Otherwise continue.
 
 ### Step 2. Detect Project Type
 
@@ -216,11 +230,16 @@ node ~/.claude/bin/qualia-ui.js banner research
 mkdir -p .planning/research
 ```
 
-Say: **"Running 4 parallel research agents (stack, features, architecture, pitfalls)..."**
+**Research scope branches on `PROJECT_TYPE`:**
+
+- **Demo** (`PROJECT_TYPE=demo`): pass `<scope>quick</scope>` to all 4 researchers AND the synthesizer. Each researcher gets a 3-call budget instead of 8. The synthesizer produces a single-milestone suggestion (no Handoff, no multi-milestone arc). Total research time drops roughly 3x with no loss of correctness on the demo path — the depth was wasted when there's only one milestone to ship.
+- **Full project** (`PROJECT_TYPE=full`): standard scope, 8-call budget per researcher, full milestone-arc synthesis.
 
-Spawn 4 researchers in parallel (single message, 4 Agent tool calls), with multi-milestone scope. See REFERENCE.md section "Researcher prompts (4 dimensions)" for the verbatim prompt templates.
+Say: **"Running 4 parallel research agents (stack, features, architecture, pitfalls)..."** (demo: append "— quick scope").
 
-**After all 4 complete, spawn synthesizer.** See REFERENCE.md section "Synthesizer prompt" for the verbatim prompt template.
+Spawn 4 researchers in parallel (single message, 4 Agent tool calls). See REFERENCE.md section "Researcher prompts (4 dimensions)" for the verbatim prompt templates. Include `<scope>quick</scope>` in each prompt when `PROJECT_TYPE=demo`.
+
+**After all 4 complete, spawn synthesizer.** See REFERENCE.md section "Synthesizer prompt" for the verbatim prompt template. Include `<scope>quick</scope>` when `PROJECT_TYPE=demo`.
 
 **Commit:**
 ```bash
@@ -258,7 +277,12 @@ Gather any additional requirements the user wants that research missed.
 node ~/.claude/bin/qualia-ui.js banner roadmap
 ```
 
-Spawn the roadmapper with full-journey mandate. If the user passed `--full-detail`, include `<full_detail>true</full_detail>` in the prompt so the roadmapper writes complete phase detail for ALL milestones. See REFERENCE.md section "Roadmapper prompt" for the verbatim prompt template.
+**Roadmapper output branches on `PROJECT_TYPE`:**
+
+- **Demo** (`PROJECT_TYPE=demo`): roadmapper produces a 1-milestone JOURNEY.md (the demo milestone, 2-4 phases) plus a matching REQUIREMENTS.md and a fully-detailed ROADMAP.md. No "Handoff" milestone is appended — the demo is its own complete artifact. The journey-tree at Step 11 shows a single rung; the "extend to full project" branch is handled later by `/qualia-milestone` if the client signs.
+- **Full project** (`PROJECT_TYPE=full`): roadmapper produces the standard 2-5 milestone arc ending in Handoff. Milestone 1 fully detailed, M2..M{N-1} sketched (unless `--full-detail`).
+
+Spawn the roadmapper with `<project_type>$PROJECT_TYPE</project_type>` in the prompt. If the user passed `--full-detail`, include `<full_detail>true</full_detail>` so the roadmapper writes complete phase detail for ALL milestones (full project only; demo always has full detail because there's only one milestone). See REFERENCE.md section "Roadmapper prompt" for the verbatim prompt template.
 
 ### Step 11. Present the Journey (single view)
 
@@ -366,12 +390,15 @@ Do NOT use `--quick` for: client projects, anything with compliance stakes, anyt
 
 ## Rules
 
-1. **Research runs automatically.** No permission ask. Only `--quick` skips it. This is a v4 invariant.
-2. **The journey includes Handoff.** Every project's final milestone is literally named "Handoff" with 4 standard phases. The roadmapper enforces this.
-3. **Single approval gate.** One gate for the whole journey. Not per-milestone, not per-phase.
-4. **Milestone count: 2-5.** Hard floor 2, hard ceiling 5. Bigger projects defer remainder to post-handoff v2.
-5. **Milestone 1 is fully detailed.** M2..M{N-1} are sketched. Detail fills in when each milestone opens.
-6. **STATE.md through state.js.** Never edit STATE.md or tracking.json by hand.
-7. **Inline skill invocation.** When Step 0.5 offers `/qualia-map`, invoke it inline — don't exit.
-8. **CONTEXT.md is mandatory (v5.0).** Every project gets a domain glossary at `.planning/CONTEXT.md`. Seeded from questioning answers. Loaded by every road agent. Kept terse.
-9. **ADRs are scarce.** `.planning/decisions/` exists from day one but only fills with hard-to-reverse, surprising-without-context, real-tradeoff decisions. Cargo-culting ADRs ruins the signal.
+1. **Project type is the first fork.** Step 0.6 asks Demo vs Full Project. Every downstream step branches on this. Don't skip it, don't infer it.
+2. **Discovery interview is mandatory (v5.6).** Step 1 always invokes `/qualia-discuss` in PROJECT MODE. No free-form questioning loop, no "I'll just sketch PROJECT.md from the user's first message." The interview is 8 questions for demo, 14 for full project.
+3. **Research runs automatically.** No permission ask. Only `--quick` skips it. Demo path uses `<scope>quick</scope>` (3-call budget per researcher); full project uses standard 8-call budget.
+4. **Demo design philosophy is non-negotiable.** Real backend always, DESIGN.md mandatory, slop-detect hard-block. Speed comes from skipping multi-milestone planning, never from skipping design quality or mocking the backend. A demo that uses mock data is not a Qualia demo.
+5. **Demos are 1 milestone, full projects are 2-5.** Demo journeys have no "Handoff" — the demo IS the artifact. Full projects always end in Handoff (fixed 4 phases). The journey-tree adapts to both shapes.
+6. **The full-project journey includes Handoff.** Every full project's final milestone is literally named "Handoff" with 4 standard phases. The roadmapper enforces this.
+7. **Single approval gate.** One gate for the whole journey. Not per-milestone, not per-phase.
+8. **Milestone 1 is fully detailed (full projects).** M2..M{N-1} are sketched. Detail fills in when each milestone opens. Demos are always fully detailed because they're 1 milestone.
+9. **STATE.md through state.js.** Never edit STATE.md or tracking.json by hand.
+10. **Inline skill invocation.** When Step 0.5 offers `/qualia-map` or Step 1 invokes `/qualia-discuss`, invoke it inline — don't exit.
+11. **CONTEXT.md is mandatory.** Every project gets a domain glossary at `.planning/CONTEXT.md`. Seeded from the discovery interview answers. Loaded by every road agent. Kept terse.
+12. **ADRs are scarce.** `.planning/decisions/` exists from day one but only fills with hard-to-reverse, surprising-without-context, real-tradeoff decisions. Cargo-culting ADRs ruins the signal.

package/skills/qualia-optimize/SKILL.md

@@ -146,7 +146,7 @@ Collect all 3 proposals. Present to the user as a side-by-side table:
 | 2 | ... | ... | ... | ... |
 | 3 | ... | ... | ... | ... |
 
-User picks `1`, `2`, `3`, or `hybrid` (with notes on which elements from which proposals to combine). The synthesizer then writes a "Refactor RFC" to `.planning/REFACTOR-{slug}.md` and optionally opens a GH issue (mirrors `/qualia-prd` flow).
+User picks `1`, `2`, `3`, or `hybrid` (with notes on which elements from which proposals to combine). The synthesizer then writes a "Refactor RFC" to `.planning/REFACTOR-{slug}.md` and optionally opens a GH issue.
 
 **Why parallel + radically different**: a single deepening proposal anchors on the first idea the LLM has. Three parallel proposals with diverse design constraints surface trade-offs the user can see at a glance — and the human's "taste" dominates the choice rather than the agent's first instinct. Empirically (Matt Pocock + Qualia internal testing) this produces dramatically better refactor RFCs than a single-pass proposal.