qualia-framework 6.2.10 → 6.4.0

package/hooks/pre-deploy-gate.js

@@ -21,6 +21,8 @@ function qualiaHome() {
 }
 
 const QUALIA_HOME = qualiaHome();
+const CONFIG = path.join(QUALIA_HOME, ".qualia-config.json");
+let HOOK_COMMAND = null;
 
 // Self-filter on the proposed bash command — only act when the user is
 // actually trying to deploy. Claude Code's `if: "Bash(vercel --prod*)"` does
@@ -44,7 +46,8 @@ const QUALIA_HOME = qualiaHome();
     }
   } catch {}
   if (command === null) return; // malformed or empty stdin — run full gate
-  if (!/^\s*(npx\s+)?vercel\s+(--prod|deploy\s+--prod)\b/.test(command)) {
+  HOOK_COMMAND = command;
+  if (!/^\s*(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(npx\s+)?vercel\s+(--prod|deploy\s+--prod)\b/.test(command)) {
     process.exit(0);
   }
 })();
@@ -107,6 +110,76 @@ function hasScript(name) {
   }
 }
 
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function readTrackingState() {
+  try {
+    const tracking = JSON.parse(fs.readFileSync(path.join(process.cwd(), ".planning", "tracking.json"), "utf8"));
+    return {
+      status: tracking.status || "",
+      verification: tracking.verification || "",
+      next_command: tracking.next_command || "",
+    };
+  } catch {
+    return null;
+  }
+}
+
+function readState() {
+  const stateJs = path.join(QUALIA_HOME, "bin", "state.js");
+  if (fs.existsSync(stateJs)) {
+    try {
+      const r = spawnSync(process.execPath, [stateJs, "check"], {
+        encoding: "utf8",
+        timeout: 3000,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      if (r.status === 0 && r.stdout) return JSON.parse(r.stdout);
+    } catch {}
+  }
+  return readTrackingState();
+}
+
+function blockDeploy(reason, nextCommand) {
+  console.error(`BLOCKED: ${reason}`);
+  if (nextCommand) console.error(`Run: ${nextCommand}`);
+  _trace("pre-deploy-gate", "block", { reason, next_command: nextCommand || "" });
+  process.exit(2);
+}
+
+function enforceShipPolicy() {
+  if (!HOOK_COMMAND) return;
+
+  const config = readConfig();
+  const role = String(config.role || "").toUpperCase();
+  const force = process.env.QUALIA_SHIP_FORCE === "1" || /\bQUALIA_SHIP_FORCE=1\b/.test(HOOK_COMMAND);
+  const state = readState();
+  const status = state && state.status ? String(state.status) : "";
+  const verification = state && state.verification ? String(state.verification) : "";
+  const nextCommand = (state && state.next_command) || "/qualia";
+
+  if (force && role !== "OWNER") {
+    blockDeploy("QUALIA_SHIP_FORCE is OWNER-only.", nextCommand);
+  }
+
+  // If this is not a Qualia-managed project, keep the legacy behavior: run the
+  // quality/security gates but do not invent state.
+  if (!state || !status) return;
+
+  const shippable = status === "polished" || (status === "verified" && verification === "pass");
+  if (!shippable && !force) {
+    blockDeploy(`Ship refused from state '${status}' (verification: ${verification || "none"}).`, nextCommand);
+  }
+}
+
+enforceShipPolicy();
+
 // Directories that should never be walked (build outputs, deps, caches).
 const EXCLUDED_DIRS = new Set([
   "node_modules",

package/hooks/session-start.js

@@ -25,6 +25,9 @@ function qualiaHome() {
   if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
   const parent = path.basename(path.dirname(__dirname));
   if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  if (fs.existsSync(path.join(path.dirname(__dirname), "bin", "qualia-ui.js"))) {
+    return path.dirname(__dirname);
+  }
   return path.join(HOME, ".claude");
 }
 
@@ -36,6 +39,7 @@ const NOTIF_FILE = path.join(QUALIA_HOME, ".qualia-update-available.json");
 const HEALTH_FILE = path.join(QUALIA_HOME, ".qualia-install-health.json");
 const ERP_RETRY = path.join(QUALIA_HOME, "bin", "erp-retry.js");
 const ERP_QUEUE = path.join(QUALIA_HOME, ".erp-retry-queue.json");
+const WORK_PACKET_BIN = path.join(QUALIA_HOME, "bin", "work-packet.js");
 
 // Critical files referenced by skills via @-import. If any are missing, skills
 // silently get empty context and produce ungrounded output. We spot-check these
@@ -97,6 +101,29 @@ function getNextCommand() {
   }
 }
 
+function readWorkPacket() {
+  try {
+    if (!fs.existsSync(WORK_PACKET_BIN)) return null;
+    const mod = require(WORK_PACKET_BIN);
+    if (!mod || typeof mod.readLocalWorkPacket !== "function") return null;
+    return mod.readLocalWorkPacket(process.cwd());
+  } catch {
+    return null;
+  }
+}
+
+function renderWorkPacketContext() {
+  const packet = readWorkPacket();
+  if (!packet) return;
+  const project = packet.project && packet.project.name ? packet.project.name : "ERP mission";
+  const deadline = packet.deadline_date || "no deadline";
+  const next = packet.next_command || "/qualia";
+  const employee = packet.employee && packet.employee.name ? ` · ${packet.employee.name}` : "";
+  const text = `${project}: due ${deadline} · next ${next}${employee}`;
+  if (fs.existsSync(UI)) runUi("info", text);
+  else console.log(`QUALIA: ${text}`);
+}
+
 function readConfig() {
   try {
     return JSON.parse(fs.readFileSync(path.join(QUALIA_HOME, ".qualia-config.json"), "utf8"));
@@ -178,6 +205,7 @@ try {
     fallbackText();
   } else if (fs.existsSync(STATE_FILE)) {
     runUi("banner", "router");
+    renderWorkPacketContext();
     const next = getNextCommand();
     if (next) {
       console.log("");
@@ -185,7 +213,7 @@ try {
     }
   } else if (fs.existsSync(CONTINUE_HERE)) {
     runUi("banner", "resume");
-    runUi("warn", "Previous session found — type /qualia-resume to pick up where you left off");
+    runUi("warn", "Previous session found — type /qualia to pick up where you left off");
     console.log("");
   } else {
     // No project — show a welcoming first-run experience

package/package.json

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

package/qualia-design/frontend.md

@@ -115,8 +115,8 @@ For redesigns and full-app polish, also read:
 
 ## Qualia design commands
 - `/qualia-polish` — design pass, scope-adaptive (component / section / app / redesign / critique / quick / loop)
-- `/qualia-vibe` — fast aesthetic pivot (swap tokens, keep layout) + reverse-engineer from URL + code↔DESIGN.md sync
+- `/qualia-polish --vibe` — fast aesthetic pivot (swap tokens, keep layout) + reverse-engineer from URL + code↔DESIGN.md sync
 - `/qualia-review` — scored production audit
 
 ### Recommended workflow
-1. Build feature → 2. `/qualia-polish` to polish within the current vibe → 3. `/qualia-vibe` when the vibe itself needs to change → 4. `/qualia-polish --redesign` when the whole surface needs stronger visual concept/graphics → 5. `/qualia-polish --loop` for autonomous visual QA → ship.
+1. Build feature → 2. `/qualia-polish` to polish within the current vibe → 3. `/qualia-polish --vibe` when the vibe itself needs to change → 4. `/qualia-polish --redesign` when the whole surface needs stronger visual concept/graphics → 5. `/qualia-polish --loop` for autonomous visual QA → ship.

package/rules/codex-goal.md

@@ -39,7 +39,7 @@ If the answer is `claude`, **skip this entire rule** — Claude Code has no equi
 
 - The user is on Claude Code (no `/goal` surface).
 - A goal is already active for this thread (Codex rejects `update_goal` when one exists — call `thread/goal/get` first if you're using the tool API directly).
-- The work is open-ended exploration with no clear objective (e.g. `/qualia-idk`, `/qualia-discuss`). Goals are for executing a defined scope.
+- The work is open-ended exploration with no clear objective (e.g. `/qualia`, `/qualia-discuss`). Goals are for executing a defined scope.
 
 ## Why
 

package/rules/one-opinion.md

@@ -1,6 +1,6 @@
 # One Opinion (design-decision discipline)
 
-Loaded on demand by design-adjacent skills: `/qualia-vibe`, `/qualia-polish`, `/qualia-new` (DESIGN.md creation step), `/qualia-discuss` PROJECT MODE. Not always-on — most skills don't need it.
+Loaded on demand by design-adjacent skills: `/qualia-polish --vibe`, `/qualia-polish`, `/qualia-new` (DESIGN.md creation step), `/qualia-discuss` PROJECT MODE. Not always-on — most skills don't need it.
 
 ## The rule
 
@@ -34,7 +34,7 @@ Owners and clients have a strong sense of what they DON'T want and a weaker sens
 - The user explicitly asked for options ("show me 3 directions", "give me a menu").
 - The decision is technical, not aesthetic (e.g. "use Postgres or MongoDB?" — those have objectively different tradeoffs and should be discussed, not opinionated).
 - A locked decision in `.planning/decisions/*.md` already exists — surface it, don't re-decide.
-- The framework command explicitly supports a `--variants` mode (e.g. `/qualia-vibe --variants 3`), which is the user opting into the menu surface.
+- The framework command explicitly supports a `--variants` mode (e.g. `/qualia-polish --vibe --variants 3`), which is the user opting into the menu surface.
 
 ## Output shape
 

package/rules/speed.md

@@ -50,5 +50,4 @@ When a Qualia command exists for the situation, use it — don't reinvent:
 - `/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
 - `/qualia-learn` — save a lesson from a mistake

package/skills/qualia/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia
-description: "Smart router — reads project state (state.js), classifies the situation mechanically, returns the exact next command. Use whenever you type /qualia, 'what next', 'next', 'what now', 'what should I do next', 'what command now'. For deeper 'I don't understand what's going on' / 'something feels off' situations, use /qualia-idk instead — that one actually scans the planning folder and codebase to diagnose the confusion."
+description: "Mechanical state-driven router — reads state.js, returns the exact next command. Cheap and instant. Triggers: '/qualia', 'what next', 'what now'. For deeper situational confusion use /qualia-idk."
 allowed-tools:
   - Bash
   - Read
@@ -39,7 +39,7 @@ Use the state.js JSON output plus gathered context:
 |-----------|-----------|-------|
 | `no-project` | state.js returns NO_PROJECT | → `/qualia-new` |
 | `handoff` | `.continue-here.md` exists | → Read it, summarize, route to next step |
-| `mid-work` | Uncommitted changes + phase in progress | → Continue or `/qualia-pause` |
+| `mid-work` | Uncommitted changes + phase in progress | → Continue, or write `.continue-here.md` if the user wants to pause |
 | `ready-to-plan` | status == "setup" | → `/qualia-plan {N}` |
 | `ready-to-build` | status == "planned" | → `/qualia-build {N}` |
 | `ready-to-verify` | status == "built" | → `/qualia-verify {N}` |
@@ -50,8 +50,8 @@ Use the state.js JSON output plus gathered context:
 | `polished` | status == "polished" | → `/qualia-ship` |
 | `shipped` | status == "shipped" | → `/qualia-handoff` |
 | `handed-off` | status == "handed_off" | → `/qualia-report` then done |
-| `blocked` | STATE.md lists blockers or same error 3+ times | → Analyze; `/qualia-fix` if expected behavior is known, `/qualia-debug` if not |
-| `bug-loop` | Same files edited 3+ times, user frustrated | → Different approach, `/qualia-fix` if actionable, `/qualia-debug` if evidence is missing |
+| `blocked` | STATE.md lists blockers or same error 3+ times | → Diagnose the evidence; `/qualia-fix` if expected behavior is known, `/qualia-review` if broader audit is needed |
+| `bug-loop` | Same files edited 3+ times, user frustrated | → Stop patching; summarize root cause evidence and route to `/qualia-fix` or `/qualia-review` |
 | `need-tests` | User mentions "tests", "coverage", "test this" | → `/qualia-test` |
 
 **Employee escalation:** If role is EMPLOYEE and situation is `gap-limit` or `bug-loop`, suggest: "Want to flag this for Fawzi?"

package/skills/qualia-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-build
-description: "Executes a planned phase by spawning fresh builder subagents per task with wave-based parallelization. Each task gets isolated context, commits atomically, and runs its own validation. Use when the user says 'build this phase', 'execute the plan', 'start building', 'run the build', 'qualia-build', or after /qualia-plan approves a phase plan."
+description: "Execute a planned phase — fresh builder subagents per task, wave-based parallelization, atomic commits, per-task validation. Triggers: 'build this phase', 'execute the plan', 'start building', 'qualia-build'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-discuss/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-discuss
-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'."
+description: "Alignment interview — PROJECT MODE before /qualia-new, PHASE MODE before /qualia-plan N. Triggers: 'discuss', 'kickoff interview', 'grill me', 'stress test this plan', 'I'm not sure how to approach this'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-doctor
-description: "Employee-facing framework health check. Wraps `qualia-framework doctor`, checks install targets, project state, contract coverage, planning-folder hygiene, hooks, memory, ERP queue health, and gives safe repair commands. Trigger on 'doctor', 'health check', 'framework broken', 'is Qualia installed correctly', 'Codex not picking up Qualia', 'hooks not running', 'memory broken', 'ERP queue stuck', '.planning messy'."
+description: "Framework health check — install, project state, contracts, hooks, memory, ERP queue. Suggests safe repair commands. Triggers: 'doctor', 'health check', 'framework broken', 'hooks not running', 'ERP queue stuck'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-feature/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-feature
-description: "Auto-scoped single feature build for adding net-new capability. Picks inline (≤1 trivial file, no spawn) or fresh builder spawn (1-5 logic files, atomic commit). Refuses and routes to /qualia-plan for phase-sized work, and routes broken existing behavior to /qualia-fix. Trigger phrases: 'build this one thing', 'add a component', 'implement this feature', 'small change', 'tweak', 'one-line copy change', 'config tweak', 'qualia-feature'."
+description: "Auto-scoped single-feature build (inline for trivia, fresh spawn for 1-5 files). Routes phase-sized work to /qualia-plan, broken behavior to /qualia-fix. Triggers: 'build this one thing', 'add a component', 'implement this feature', 'small change', 'tweak'."
 allowed-tools:
   - Bash
   - Read
@@ -35,7 +35,7 @@ One command for adding a small new capability outside the planned Road. Auto-det
 - 5+ files or multiple subsystems touched → `/qualia-plan`
 - Part of a planned phase → `/qualia-build`
 - Broken existing behavior, regression, failing test, or hotfix → `/qualia-fix`
-- Investigating a symptom you can't name yet → `/qualia-debug`
+- Investigating a symptom you can't name yet → `/qualia-review`
 - Optimization or polish pass → `/qualia-optimize` or `/qualia-polish`
 
 ## Process

package/skills/qualia-fix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-fix
-description: "Practical repair lane for broken existing behavior. Blends /qualia-debug root-cause discipline with /qualia-feature execution. Use when the user says 'fix this', 'bug', 'broken', 'error', 'failing test', 'regression', 'hotfix', 'not working', 'layout broken', 'slow page', or 'config is wrong'."
+description: "Practical repair lane for broken behavior — root-cause investigation + /qualia-feature execution. Triggers: 'fix this', 'bug', 'broken', 'error', 'failing test', 'regression', 'hotfix', 'layout broken', 'slow page'."
 allowed-tools:
   - Bash
   - Read
@@ -14,7 +14,7 @@ argument-hint: "[--quick|--frontend|--perf|--test|--no-commit] <symptom>"
 
 # /qualia-fix - Repair Broken Existing Behavior
 
-Fix is the practical lane for "this used to work, or should work, and now it does not." It combines the evidence discipline of `/qualia-debug` with the small-work execution path of `/qualia-feature`.
+Fix is the practical lane for "this used to work, or should work, and now it does not." It combines root-cause evidence gathering with the small-work execution path of `/qualia-feature`.
 
 ## Usage
 
@@ -38,9 +38,9 @@ Fix is the practical lane for "this used to work, or should work, and now it doe
 - Net-new capability -> `/qualia-feature`
 - Phase-sized work or 5+ likely files -> `/qualia-plan`
 - Read-only audit -> `/qualia-review`
-- No concrete symptom and no failing command -> `/qualia-debug`
+- No concrete symptom and no failing command -> `/qualia-review`
 - Visual craft/design quality with no functional bug -> `/qualia-polish`
-- Whole-site aesthetic pivot -> `/qualia-vibe`
+- Whole-site aesthetic pivot -> `/qualia-polish --vibe`
 
 ## Process
 

package/skills/qualia-idk/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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'."
+description: "Deep diagnostic for 'I don't know what's going on.' Reads conversation context + the planning folder + the codebase in three isolated scans, cross-references against the user's confusion, then returns plain-language guidance PLUS a paste-ready Qualia command sequence to unstick them. 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', 'where am I', 'lost'."
 allowed-tools:
   - Bash
   - Read
@@ -11,18 +11,18 @@ allowed-tools:
 
 # /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*.
+Not a router. A **diagnostician**. Use when the user isn't stuck on a single command — they're stuck on **understanding the situation**. Returns guidance + a Qualia command sequence the user can paste.
 
 ## 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 |
+| Mechanical: reads state.js, returns one `/qualia-X` | Interpretive: reads conversation + planning + code |
+| "What's my next command?" | "What is happening, and what sequence gets me unstuck?" |
+| Always returns a skill name | Returns plain-language guidance + a multi-command sequence |
+| Cheap, instant (~2s) | Three parallel scans, ~30–45s |
 
-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*.
+Run `/qualia` when the user knows what they're trying to do. Run `/qualia-idk` when the user's confusion is about **the situation itself** — scope, drift, or where to even begin.
 
 ## Process
 
@@ -30,28 +30,52 @@ Run `/qualia` first when the user knows what they're trying to do. Run `/qualia-
 
 ```bash
 node ${QUALIA_BIN}/qualia-ui.js banner router
-node ${QUALIA_BIN}/qualia-ui.js spawn "diagnostic" "Reading planning and codebase in isolation..."
+node ${QUALIA_BIN}/qualia-ui.js spawn "diagnostic" "Reading conversation, planning, and codebase in isolation..."
 ```
 
 Say: **"Let me take a proper look."**
 
-### Step 1. Gather the User's Confusion
+### Step 1. Capture the User's Confusion
 
-Look at the conversation context (if any). Note:
+Look at the recent conversation. 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?
+- Sentiment cues: "lost", "stuck", "weird", "broken", "where am I" — record verbatim.
 
-If there's nothing in conversation context yet, ask:
+If conversation context is thin, ask:
 - header: "What's unclear?"
 - question: "Where are you stuck? (one sentence is fine)"
 - Free text.
 
-Store this as `<user_confusion>`.
+Store as `<user_confusion>`.
 
-### Step 2. Spawn Two Isolated Scans (Parallel)
+### Step 2. Capture Session Context (local, fast)
 
-Two fresh subagents. Each sees ONLY its respective scope — no cross-contamination.
+Before spawning scans, gather cheap session signals:
+
+```bash
+# Where is the user right now?
+test -f .continue-here.md && head -30 .continue-here.md
+test -f .planning/STATE.md && head -20 .planning/STATE.md
+git log --oneline -5 2>/dev/null
+git status --short 2>/dev/null | head -10
+
+# Recent planning artifacts (mtime tells us what was last touched)
+ls -lt .planning/phase-*-*.md 2>/dev/null | head -8
+ls -lt .planning/decisions/*.md 2>/dev/null | head -5
+
+# Is there a halt / FAIL we should know about?
+grep -l "FAIL\|INSUFFICIENT EVIDENCE\|HALT" .planning/phase-*-verification.md 2>/dev/null
+```
+
+Store as `<session_context>`.
+
+### Step 3. Spawn Three Isolated Scans (Parallel)
+
+Three fresh subagents. Each sees ONLY its scope — no cross-contamination. They run in parallel; wait for all three.
+
+**Agent A — Planning View** (broader than v1: now reads CONTEXT, REQUIREMENTS, decisions/, all phase artifacts, not just the latest):
 
 ```
 Agent(prompt="
@@ -59,14 +83,18 @@ You are a read-only diagnostic scanner for the .planning/ folder only.
 
 Read ALL of the following if present:
   - .planning/PROJECT.md
+  - .planning/CONTEXT.md (domain glossary)
   - .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/phase-*-plan.md (ALL, not just latest)
+  - .planning/phase-*-verification.md (ALL — flag any FAILs)
+  - .planning/phase-*-context.md (from /qualia-discuss PHASE MODE, if any)
+  - .planning/phase-*-research.md (if any)
   - .planning/DESIGN.md (skim)
+  - .planning/decisions/*.md (ADRs — short read)
   - .continue-here.md (if present)
 
 DO NOT read any source code — no src/, app/, components/, lib/, etc.
@@ -74,14 +102,20 @@ 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.
+  2. Where does the plan say we ARE? (current milestone N of M + phase P of Q + status)
+  3. What SHOULD be true right now? (current phase's acceptance criteria)
+  4. What's UNFINISHED? (upcoming phases / unresolved gaps from latest verification)
+  5. Plan-level inconsistencies? (tracking.json vs STATE.md mismatch, JOURNEY.md missing, roadmap drift)
+  6. Has any verification FAILED recently? Quote the FAIL summary if so.
+  7. Are there hard decisions (ADRs in decisions/) that constrain the next step?
+
+Keep it under 350 words. Be specific. No filler. Quote file:line for anything you assert.
 ", subagent_type="Explore", description="Plan-view scan")
+```
 
+**Agent B — Code View** (unchanged from v1):
+
+```
 Agent(prompt="
 You are a read-only diagnostic scanner for the source code only.
 
@@ -91,75 +125,120 @@ 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
+  - Quick static checks: 'npx tsc --noEmit' output, lint errors, test status
+  - Stubs: grep for TODO, FIXME, 'not implemented', empty catch blocks, unused exports
+  - Dev server / deploy markers (vercel link, .env.local, supabase project ref)
 
 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)
+  1. What does the code LOOK LIKE it's building? (inferred from structure + imports)
+  2. What ACTUALLY WORKS right now? (compile status, recent commits, smoke signals)
+  3. What's STUBBED / INCOMPLETE? (concrete file:line citations)
+  4. What's RUNNING locally or deployed?
+  5. Code-level inconsistencies? (imports that don't resolve, routes referenced but not defined)
 
-Keep it under 250 words. Cite specific files/lines. No filler.
+Under 300 words. Cite file:line. No filler.
 ", subagent_type="Explore", description="Code-view scan")
 ```
 
-Wait for both. Don't proceed to synthesis until you have both reports.
+**Agent C — Conversation & Memory View** (new in v2):
 
-### Step 3. Synthesize
+```
+Agent(prompt="
+You are a read-only diagnostic scanner for the user's recent activity. Do NOT read .planning/ or source code.
 
-With both reports + the user's confusion in hand, cross-reference:
+Read:
+  - ${QUALIA_HOME}/knowledge/daily-log/<latest 1-2 dates>.md (recent session entries)
+  - ${QUALIA_HOME}/knowledge/concepts/<files referenced by the user's confusion>
+  - .continue-here.md (if present)
+  - git log --since='3 days ago' --oneline
+  - git diff main...HEAD --stat (work in flight)
 
-**Produce a structured diagnosis** (use this exact shape):
+Cross-reference against the user's stated confusion: ${user_confusion}
 
+Produce a 'Session View' report answering:
+  1. What has the user been doing recently? (1-3 bullets from daily log + git)
+  2. Is the user's CURRENT confusion consistent with their recent activity, or is there a discontinuity? (e.g. they were in M2-P3 yesterday but today they're asking about M3 setup)
+  3. Are there saved learnings or ADRs that directly answer the user's confusion?
+  4. Was there a recent halt, FAIL, or pause we should foreground?
+
+Under 250 words. Quote daily-log line numbers or commit SHAs.
+", subagent_type="Explore", description="Session-view scan")
 ```
+
+### Step 4. Synthesize — Diagnosis + Command Sequence
+
+With all three reports + `<user_confusion>` + `<session_context>` in hand, produce **exactly this shape**:
+
+```markdown
 ## 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".}
+**Your recent activity:** {1-2 sentences — last 2-3 days of work in flight, last commit, last skill run}
+
+**The mismatch (if any):** {1-2 sentences — where plan / code / activity disagree. If consistent, say "all three views align".}
 
 ## 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."}
+{3-5 sentences, plain language. Tie the user's confusion to what you found. No 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 phase-2-plan.md says it should be. Someone wrote the helper but forgot to wire it up — that's why verification went FAIL yesterday."}
 
-## What to do next
+## What to do next — paste-ready command sequence
 
-1. **{concrete action}** — {one sentence why}
-2. **{concrete action}** — {one sentence why}
-3. **{optional third}** — {one sentence why}
+```
+{command 1}      # {one-line reason}
+{command 2}      # {one-line reason}
+{command 3}      # {one-line reason}
+```
 
-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
+{One sentence on what this sequence accomplishes end-to-end.}
+
+## Or, if you'd rather hand-pick:
+
+1. **{action}** — {why}
+2. **{action}** — {why}
+3. **{optional}** — {why}
 ```
 
-### Step 4. Close
+**Command-sequence picking rules** — choose from these established patterns:
+
+| Situation found | Sequence |
+|---|---|
+| Plan says built but code has stubs | `/qualia-plan {N} --gaps` → `/qualia-build` → `/qualia-verify` |
+| Verify FAILed and no postmortem ran | `/qualia-postmortem` → `/qualia-plan {N} --gaps` → `/qualia-build` |
+| Stale `.continue-here.md`, ongoing context | `/qualia-resume` → `/qualia` |
+| Brownfield drift (plan and code diverged hard) | `/qualia-map` → `/qualia-plan {N} --gaps` |
+| Phase context missing (no `/qualia-discuss` ran) | `/qualia-discuss {N}` → `/qualia-plan {N}` |
+| Specific error, scope clear | `/qualia-fix '<symptom>'` |
+| Performance feels off, no profile | `/qualia-fix --perf '<route>'` or `/qualia-optimize --perf` |
+| Design feels off | `/qualia-polish --critique` then `/qualia-polish` |
+| User is overwhelmed | `/qualia-pause` (save handoff), come back later |
+| Truly nothing actionable found | Ask one specific question; don't invent a sequence |
+
+Pick the sequence that fits the actual evidence. Substitute real `{N}` from the Plan-view scan.
+
+### Step 5. Close
 
 ```bash
 node ${QUALIA_BIN}/qualia-ui.js divider
-node ${QUALIA_BIN}/qualia-ui.js end "DIAGNOSED" "{top-recommended action if it's a command, else leave blank}"
+node ${QUALIA_BIN}/qualia-ui.js end "DIAGNOSED" "{first command in the sequence, if any}"
 ```
 
 ## 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.
+1. **Three isolated scans, always.** Plan view never peeks at code or session. Code view never peeks at planning. Session view never peeks at code. This is what keeps the diagnosis honest — each agent sees one slice, 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.
+3. **No fake certainty.** If the scans come back thin (brand-new repo, no planning artifacts yet), say so explicitly: "I don't have enough signal yet — here's what I'd do to gather more."
+4. **Never invent facts.** If a scan didn't find something, don't claim it. Cite files.
+5. **Command sequence > single recommendation.** The user came here because one command isn't enough. Give them a chain.
+6. **The sequence must be paste-ready.** Real `{N}` values, real route names, no `<placeholder>` text outside the optional "if you'd rather hand-pick" section.
+7. **Don't re-run if `/qualia` already knows.** If the user's confusion is purely "what's my next command", `/qualia` handles it cheaper — gently suggest it and stop.
 
 ## 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 has a specific error message they want fixed → `/qualia-fix '<symptom>'`
 - User wants to review code quality → `/qualia-review`
 - User wants to pause and come back → `/qualia-pause`