qualia-framework 5.5.0 → 5.8.0

package/README.md

@@ -1,14 +1,18 @@
-# Qualia Framework v5.3
+# Qualia Framework v5.8
 
 A harness engineering framework for [Claude Code](https://claude.ai/code). It installs into `~/.claude/` and wraps your AI-assisted development workflow with structured planning, execution, verification, and deployment gates.
 
-It is not an application framework like Rails or Next.js. It doesn't generate code, run servers, or process data. It's an opinionated workflow layer that tells Claude how to plan, build, and verify your projects — end-to-end, from "tell me what you want to make" to "here's the handoff doc for your client."
+It is not an application framework like Rails or Next.js. It doesn't generate code, run servers, or process data. It's an opinionated workflow layer that tells Claude how to plan, build, and verify your projects end-to-end, from "tell me what you want to make" to "here's the handoff doc for your client."
 
-**The v5 line in three releases:**
-- **v5.0** — alignment discipline. CONTEXT.md domain glossary, decisions/ ADRs, `/qualia-zoom`, `/qualia-issues`, `/qualia-triage`, slim CLAUDE.md per Matt Pocock's instruction-budget rule, insights-driven hooks (Vercel account, empty env-var, Supabase destructive guards).
-- **v5.1** — `/qualia-polish-loop` (autonomous visual-polish loop: screenshots a URL at three viewports, scores 8 design dimensions with vision, fixes top issues, loops until pass or kill-switch); multi-target installer (Claude Code + Codex AGENTS.md + Both); live-progress install UI.
-- **v5.2** — polish-loop reliability. `--reduced-motion` capture flag, `--routes URL1,URL2` multi-route mode, first supervised end-to-end run.
-- **v5.3** — Matt Pocock gaps closed. `/qualia-prd` (synthesize conversation → durable PRD), `/qualia-hook-gen` (CLAUDE.md instruction → deterministic Claude Code hook), `/qualia-optimize --deepen` Step 5b parallel-interface design (3 fan-out agents producing radically different interfaces).
+**The v5 line:**
+- **v5.0**, alignment discipline. CONTEXT.md domain glossary, decisions/ ADRs, `/qualia-zoom`, `/qualia-issues`, `/qualia-triage`, slim CLAUDE.md per Matt Pocock's instruction-budget rule, insights-driven hooks.
+- **v5.1**, autonomous visual-polish loop. Screenshots a URL at three viewports, scores 8 design dimensions with vision, fixes top issues, loops until pass or kill-switch. Multi-target installer (Claude Code + Codex AGENTS.md + Both).
+- **v5.2**, polish-loop reliability. `--reduced-motion` capture flag, `--routes URL1,URL2` multi-route mode, first supervised end-to-end run.
+- **v5.3**, Matt Pocock gaps closed. `/qualia-hook-gen` (CLAUDE.md instruction to deterministic Claude Code hook), `/qualia-optimize --deepen` Step 5b parallel-interface design (3 fan-out agents producing radically different interfaces).
+- **v5.4-5.5**, token-discipline and plan-discipline. Cache-aware spawn ordering, scope-reduction prohibition, decision-coverage audit, requirement-coverage check.
+- **v5.6**, Demo vs Full Project gate at kickoff. Mandatory discovery interview via `/qualia-discuss` in PROJECT MODE (8 questions for demos, 14 for full projects). Demo-extension branch in `/qualia-milestone` for client-signs-after-demo conversion.
+- **v5.7**, `/qualia-feature` consolidates `/qualia-quick` + `/qualia-task` into one auto-scoped command.
+- **v5.8**, surface cleanup. `/qualia-polish --loop` replaces `/qualia-polish-loop`. `/qualia-quick`, `/qualia-task`, and `/qualia-prd` removed (deprecated in v5.7).
 
 The Full Journey architecture carries forward: `/qualia-new` maps the entire project arc from kickoff to client handoff upfront, and the Road chains end-to-end in `--auto` mode with only two human gates per project.
 
@@ -40,6 +44,8 @@ npx qualia-framework@latest traces     # View recent hook telemetry
 
 Open Claude Code in any project directory.
 
+> **New to Qualia?** Open [`docs/onboarding.html`](docs/onboarding.html) in a browser for a one-page roadmap of the golden path. Best file to send a new hire.
+
 ### The Road — guided mode (default)
 
 ```
@@ -89,15 +95,13 @@ Two human gates per project. One halt case (gap-cycle limit exceeded on a failin
 /qualia-debug         # Structured debugging
 /qualia-review        # Production audit (scored diagnostics)
 /qualia-optimize      # Deep optimization pass (parallel specialist agents, --deepen mode with parallel-interface design)
-/qualia-quick         # Fast path for trivial fixes (skips planning)
-/qualia-task          # Build one thing properly (fresh builder, atomic commit, no phase plan)
+/qualia-feature       # Auto-scoped single-feature build (inline for trivia, fresh spawn for 1-5 files)
 /qualia-test          # Generate or run tests (--tdd mode for test-first workflow)
 /qualia-zoom          # Focus on a single file or function with full context
 /qualia-issues        # Break a phase plan into vertical-slice GitHub issues
 /qualia-triage        # Triage open issues through the ready-for-agent state machine
 /qualia-road          # View and navigate the project road (journey/milestone/phase status)
-/qualia-polish-loop   # Autonomous visual-polish loop: screenshot → vision-eval → fix → repeat (v5.1+)
-/qualia-prd           # Synthesize current conversation into a durable feature spec (v5.3+)
+/qualia-polish --loop # Autonomous visual-polish loop: screenshot, vision-eval, fix, repeat
 /qualia-hook-gen      # Convert a CLAUDE.md/rules instruction into a deterministic hook (v5.3+)
 ```
 
@@ -139,9 +143,9 @@ Project
 
 **Why it matters:** non-technical team members can follow the ladder from any entry point. `/qualia` and `/qualia-milestone` render JOURNEY.md as a visual ladder with current position highlighted. In the ERP, the primary operational dates are project deadline, milestone deadline, and employee shift submission date; framework tasks stay internal to agent execution.
 
-## What's Inside (v5.3.0)
+## What's Inside (v5.8.0)
 
-- **35 skills** — full Road (new / plan / build / verify / milestone / polish / ship / handoff / report), depth (discuss, research, map), navigation (qualia router, idk, pause, resume, road, help), quality (debug, review, optimize with `--deepen` parallel-interface design, quick, task, test, zoom, issues, triage), v5 flagships (`qualia-polish-loop`, `qualia-prd`, `qualia-hook-gen`), and meta (learn, skill-new, flush, postmortem)
+- **32 skills**, full Road (new / plan / build / verify / milestone / polish / ship / handoff / report), depth (discuss, research, map), navigation (qualia router, idk, pause, resume, road, help), quality (debug, review, optimize with `--deepen` parallel-interface design, feature, test, zoom, issues, triage), v5 flagships (`qualia-polish --loop`, `qualia-hook-gen`), and meta (learn, skill-new, flush, postmortem)
 - **9 agents** (each runs in fresh context): planner, builder, verifier, qa-browser, researcher, research-synthesizer, roadmapper, plan-checker, visual-evaluator
 - **12 hooks** (pure Node.js, cross-platform): session-start, auto-update, git-guardrails, branch-guard, pre-push tracking sync, migration-guard, pre-deploy-gate, pre-compact state save, stop-session-log, vercel-account-guard, env-empty-guard, supabase-destructive-guard
 - **6 always-loaded rules** (`rules/`): grounding, security, infrastructure, deployment, speed (CLI-first / MCP tier-list), architecture (deep modules / scout-for-shallow-code)

package/agents/research-synthesizer.md

@@ -33,6 +33,7 @@ You receive:
 - `.planning/research/ARCHITECTURE.md`
 - `.planning/research/PITFALLS.md`
 - Project context (PROJECT.md summary)
+- `<scope>` — optional: `quick` for demo projects, `standard` (default) for full projects
 
 ## Output
 
@@ -72,7 +73,9 @@ Based on:
 - ARCHITECTURE.md build order → what depends on what, which foundation must land in Milestone 1 to support final-milestone requirements
 - PITFALLS.md → which risks stall later milestones and need to be addressed in Milestone 1 foundations
 
-Suggest a **2-5 milestone arc ending in Handoff**:
+**Quick scope (`<scope>quick</scope>`, demo projects):** Suggest a **single milestone** (no Handoff, no multi-milestone arc). The milestone is the demo itself — 2 to 4 phases that ship a real working surface end-to-end. Skip the "Handoff implications" section. The demo extends into a full project later via `/qualia-milestone` if the client signs; that conversion is handled there, not here.
+
+**Standard scope (default):** Suggest a **2-5 milestone arc ending in Handoff**:
 
 - **Milestone 1 · Foundation** — almost always. DB, auth, base layout, deploy pipeline.
 - **Milestone 2-{N-1} · Core + Expansion** — the value-delivering capabilities, ordered by dependency.

package/agents/researcher.md

@@ -25,11 +25,16 @@ You receive from the orchestrator:
 - `<domain>` — the project domain (e.g., "legal case management", "dental clinic booking", "voice agent for restaurants")
 - `<project_context>` — summary of PROJECT.md (core value, constraints, what they're building)
 - `<milestone_context>` — greenfield or subsequent
+- `<scope>` — optional: `quick` for demo projects, `standard` (default) for full projects
 - `<output_path>` — absolute path where you write your research file
 
 ## Tool Budget
 
-Maximum 8 external calls total per invocation: 3 Context7 queries + 3 WebFetch calls + 2 WebSearch queries. If you exhaust this budget, write what you have and mark remaining sections as `confidence: LOW`. Research is time-boxed, not exhaustive — a 10-minute deep dive with concrete sources beats a 30-minute wander.
+**Standard scope (default):** Maximum 8 external calls total per invocation — 3 Context7 queries + 3 WebFetch calls + 2 WebSearch queries.
+
+**Quick scope (`<scope>quick</scope>`, used by demo projects):** Maximum 3 external calls total — 1 Context7 query + 1 WebFetch + 1 WebSearch. The demo only needs enough research to validate the stack and surface the top pitfall — depth is wasted when there's a single milestone to ship. Drain local sources first (Steps 0a + 0b below); if local sources cover the dimension, skip external calls entirely.
+
+If you exhaust the budget, write what you have and mark remaining sections as `confidence: LOW`. Research is time-boxed, not exhaustive — a 10-minute deep dive with concrete sources beats a 30-minute wander.
 
 **Local-first.** Before any external call, exhaust local sources (Steps 0a + 0b in *How to Research* below). Most domains have already been researched and the answers live in NotebookLM notebooks or `~/qualia-memory`. Hitting the web for content we already have is silent token waste — and the local source is usually higher-quality (curated synthesis vs raw search results).
 

package/agents/visual-evaluator.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-visual-evaluator
-description: Vision-anchored evaluator for /qualia-polish-loop. Reads screenshots, scores 8 design dimensions against the rubric with cited evidence, returns top 3 issues + severity. Default: 3 (acceptable). Only deviates with quoted evidence.
+description: Vision-anchored evaluator for /qualia-polish --loop. Reads screenshots, scores 8 design dimensions against the rubric with cited evidence, returns top 3 issues + severity. Default: 3 (acceptable). Only deviates with quoted evidence.
 tools: Read, Grep, Glob
 ---
 

package/bin/install.js

@@ -390,10 +390,10 @@ async function main() {
       if (fs.existsSync(refSrc)) {
         copy(refSrc, path.join(CLAUDE_DIR, "skills", skill, "REFERENCE.md"));
       }
-      // v5.1: Copy scripts/ subfolder if present (e.g. qualia-polish-loop ships
-      // playwright-capture.mjs, loop.mjs, score.mjs that the skill invokes at
-      // runtime). Recursive — preserves nested files. fixtures/ also copied
-      // for self-test scenarios.
+      // v5.1: Copy scripts/ subfolder if present (e.g. qualia-polish ships
+      // playwright-capture.mjs, loop.mjs, score.mjs that the --loop mode
+      // invokes at runtime). Recursive, preserves nested files. fixtures/
+      // also copied for self-test scenarios.
       for (const sub of ["scripts", "fixtures"]) {
         const subSrc = path.join(skillsDir, skill, sub);
         if (fs.existsSync(subSrc) && fs.statSync(subSrc).isDirectory()) {
@@ -893,7 +893,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     excludeDefault: true,
     tips: [
       "⬢ Lost? Type /qualia for the next step",
-      "⬢ Small fix? Use /qualia-quick to skip planning",
+      "⬢ Single feature? Use /qualia-feature, it auto-scopes",
       "⬢ End of day? /qualia-report submits your shift before clock-out",
       "⬢ Context isolation: every task gets a fresh AI brain",
       "⬢ The verifier doesn't trust claims — it greps the code",
@@ -1104,7 +1104,7 @@ function printSummary({ member, target, claudeInstalled }) {
   }
   console.log("");
   console.log(`  ${DIM}New project?${RESET}    ${TEAL}/qualia-new${RESET}`);
-  console.log(`  ${DIM}Quick fix?${RESET}      ${TEAL}/qualia-quick${RESET}`);
+  console.log(`  ${DIM}Single feature?${RESET} ${TEAL}/qualia-feature${RESET}`);
   console.log(`  ${DIM}End of day?${RESET}     ${TEAL}/qualia-report${RESET} ${DIM}(shift submission)${RESET}`);
   console.log(`  ${DIM}Stuck?${RESET}          ${TEAL}/qualia${RESET}`);
   console.log("");

package/bin/slop-detect.mjs

@@ -187,7 +187,7 @@ const SKIP_DIRS = new Set([
   "coverage", ".cache", "out", ".vercel", ".vscode", ".idea",
   ".planning", ".qa-screenshots",
   // v5.1: skip test fixtures by convention. Fixtures used as regression
-  // targets (e.g. /qualia-polish-loop's broken.html) intentionally violate
+  // targets (e.g. /qualia-polish --loop's broken.html) intentionally violate
   // the rules slop-detect enforces; scanning them flags real fixture bugs
   // as production slop.
   "fixtures", "__fixtures__",