qualia-framework 3.4.0 → 4.0.0

package/skills/qualia-idk/SKILL.md

@@ -1,8 +1,160 @@
 ---
 name: qualia-idk
-description: "Alias for /qualia. The smart router handles all 'idk', 'what now', 'I'm stuck' situations."
+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'."
 ---
 
-# /qualia-idk
+# /qualia-idk — "I Don't Know What's Going On"
 
-This is an alias for `/qualia`. Run `/qualia` — it now handles all situation classification and routing.
+Not a router. A **diagnostician**. Use when the user isn't stuck on a command — they're stuck on *understanding*.
+
+## How This Differs from `/qualia`
+
+| `/qualia` | `/qualia-idk` |
+|---|---|
+| Mechanical: reads state.js, returns `/qualia-X` | Interpretive: reads the project + the code + the confusion |
+| "What command do I run next?" | "What is actually going on here?" |
+| Always returns a skill name | Returns an explanation + a recommendation |
+| Cheap, instant | Spawns 2 isolated agents, ~30s |
+
+Run `/qualia` first when the user knows what they're trying to do. Run `/qualia-idk` when the user's confusion is about the *situation itself*.
+
+## Process
+
+### Step 0. Banner
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner router
+node ~/.claude/bin/qualia-ui.js spawn "diagnostic" "Reading planning and codebase in isolation..."
+```
+
+Say: **"Let me take a proper look."**
+
+### Step 1. Gather the User's Confusion
+
+Look at the conversation context (if any). Note:
+- What did the user just say or ask?
+- Any recent errors, failed commands, surprising output?
+- Any mismatch between what they expected and what happened?
+
+If there's nothing in conversation context yet, ask:
+- header: "What's unclear?"
+- question: "Where are you stuck? (one sentence is fine)"
+- Free text.
+
+Store this as `<user_confusion>`.
+
+### Step 2. Spawn Two Isolated Scans (Parallel)
+
+Two fresh subagents. Each sees ONLY its respective scope — no cross-contamination.
+
+```
+Agent(prompt="
+You are a read-only diagnostic scanner for the .planning/ folder only.
+
+Read ALL of the following if present:
+  - .planning/PROJECT.md
+  - .planning/JOURNEY.md
+  - .planning/REQUIREMENTS.md
+  - .planning/ROADMAP.md
+  - .planning/STATE.md
+  - .planning/tracking.json
+  - .planning/phase-*-plan.md (latest 1-2)
+  - .planning/phase-*-verification.md (latest 1-2)
+  - .planning/DESIGN.md (skim)
+  - .continue-here.md (if present)
+
+DO NOT read any source code — no src/, app/, components/, lib/, etc.
+DO NOT run any build tools.
+
+Produce a 'Plan View' report answering:
+  1. What is this project? (one sentence from PROJECT.md)
+  2. Where does the plan say we ARE? (current milestone + phase + status)
+  3. What does the plan say should be TRUE right now? (current phase's acceptance criteria / success criteria)
+  4. What does the plan say is UNFINISHED? (upcoming phases or unresolved gaps from latest verification)
+  5. Any plan-level inconsistencies? (e.g. tracking.json says phase 3 but STATE.md says phase 2, JOURNEY.md missing, roadmap out of sync)
+
+Keep it under 250 words. Be specific. No filler.
+", subagent_type="Explore", description="Plan-view scan")
+
+Agent(prompt="
+You are a read-only diagnostic scanner for the source code only.
+
+DO NOT read anything in .planning/ — skip it entirely.
+
+Scan the repo:
+  - Package/framework detection (package.json, requirements.txt, etc.)
+  - Entry points (app/, src/, pages/, index.*)
+  - Key files referenced in recent commits (git log --oneline -5, then inspect)
+  - Run quick static checks if applicable: 'npx tsc --noEmit' output, lint errors, test status
+  - Look for stubs: grep for TODO, FIXME, 'not implemented', empty catch blocks, unused exports
+
+Produce a 'Code View' report answering:
+  1. What does the code look like it's BUILDING? (inferred from structure + imports, not from docs)
+  2. What ACTUALLY WORKS right now? (compile status, recent commit messages, any obvious smoke signals)
+  3. What's STUBBED or INCOMPLETE? (concrete file:line citations)
+  4. What's RUNNING locally or deployed? (if there's a dev server log, vercel link, supabase project — flag it)
+  5. Any code-level inconsistencies? (imports that don't resolve, routes referenced but not defined, schema mismatches)
+
+Keep it under 250 words. Cite specific files/lines. No filler.
+", subagent_type="Explore", description="Code-view scan")
+```
+
+Wait for both. Don't proceed to synthesis until you have both reports.
+
+### Step 3. Synthesize
+
+With both reports + the user's confusion in hand, cross-reference:
+
+**Produce a structured diagnosis** (use this exact shape):
+
+```
+## What I see
+
+**The plan says:** {1-2 sentences — current milestone/phase/status, what should be true}
+
+**The code says:** {1-2 sentences — what actually exists, what works, what's stubbed}
+
+**The mismatch (if any):** {1-2 sentences — where plan and code disagree. If no mismatch, say "plan and code are consistent".}
+
+## What I think is happening
+
+{3-5 sentences, plain language. Tie the user's confusion to what you found. Avoid jargon. If the user said "the login is broken", don't say "the auth middleware has a type inference issue" — say "you're seeing the login fail because the signin function isn't actually imported into the login page, even though the plan says it should be. Someone wrote the helper but forgot to wire it up."}
+
+## What to do next
+
+1. **{concrete action}** — {one sentence why}
+2. **{concrete action}** — {one sentence why}
+3. **{optional third}** — {one sentence why}
+
+If one of these maps to an existing Qualia command, use it:
+  - `/qualia-plan {N} --gaps` if the mismatch is "plan says X but code has stubs"
+  - `/qualia-verify {N}` if the mismatch is "code says built but no verification exists"
+  - `/qualia-debug` if a specific error is the block
+  - `/qualia-map` if the plan and code have drifted far apart
+  - `/qualia-pause` if the user is overwhelmed and should step away
+```
+
+### Step 4. Close
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js end "DIAGNOSED" "{top-recommended action if it's a command, else leave blank}"
+```
+
+## Rules
+
+1. **Two isolated scans, always.** Plan view never peeks at code, code view never peeks at planning. This is what keeps the diagnosis honest — each agent sees one side of the story, and the synthesis catches the delta.
+2. **Plain language over jargon.** If you can't explain it to a non-dev, rewrite it.
+3. **No fake certainty.** If the scans come back thin (e.g., brand new repo), say "I don't have enough signal yet — here's what I'd do to gather more."
+4. **Never invent facts.** If the code-view scan didn't find something, don't say it exists. Cite files.
+5. **One recommendation primary, two backups.** Decision fatigue is the problem — give the user a lead option.
+6. **Don't re-run if state.js already knows.** If the user's confusion is purely "what's my next command", `/qualia` already handles that — gently suggest it instead of spawning agents.
+
+## When NOT to Use
+
+- User knows what they're doing and just wants the next command → `/qualia`
+- User has a specific error message → `/qualia-debug`
+- User wants to review code quality → `/qualia-review`
+- User wants to pause and come back → `/qualia-pause`
+
+`/qualia-idk` is specifically for **"I'm not sure what I'm even looking at"** situations. Route to sharper tools when the question is sharper.

package/skills/qualia-map/SKILL.md

@@ -47,28 +47,28 @@ Map 4 dimensions in parallel for speed. Each writes one file in `.planning/codeb
 
 ```
 Agent 1: Architecture scanner
-  Task(prompt="
+  Agent(prompt="
   Scan the current codebase and produce .planning/codebase/architecture.md.
   Identify: entry points, folder structure, module boundaries, data flow.
   Focus on WHAT the codebase does, not HOW to fix it.
   ", subagent_type="general-purpose", description="Architecture scan")
 
 Agent 2: Stack detector
-  Task(prompt="
+  Agent(prompt="
   Detect the tech stack. Read package.json, requirements.txt, Gemfile, etc.
   Produce .planning/codebase/stack.md listing: runtime, framework, key libraries,
   database, hosting, CI. Include version numbers.
   ", subagent_type="general-purpose", description="Stack detection")
 
 Agent 3: Conventions analyzer
-  Task(prompt="
+  Agent(prompt="
   Analyze code style and conventions. Sample 10-15 files across the codebase.
   Produce .planning/codebase/conventions.md listing: naming, component patterns,
   file organization, import style, test style, commit message format.
   ", subagent_type="general-purpose", description="Conventions analysis")
 
 Agent 4: Concerns scanner
-  Task(prompt="
+  Agent(prompt="
   Scan for code quality concerns — NOT to fix, just to document.
   Look for: TODO/FIXME, deprecated APIs, outdated dependencies, missing tests,
   security smells (hardcoded secrets, no input validation).

package/skills/qualia-milestone/SKILL.md

@@ -1,160 +1,203 @@
 ---
 name: qualia-milestone
-description: "Close out a completed milestone and prep the next one. Archives the current milestone's artifacts, updates REQUIREMENTS.md to mark v1 requirements Complete, and creates the next milestone roadmap."
+description: "Close the current milestone and open the next one — loads the next milestone's scope from JOURNEY.md (no ad-hoc naming). Archives artifacts, marks requirements Complete, regenerates ROADMAP.md for the next milestone."
 ---
 
 # /qualia-milestone — Milestone Closeout
 
-Use when all feature phases in the current milestone are verified. Archives artifacts, marks requirements Complete, opens a new milestone for the next release.
+Triggered after `/qualia-verify` passes on the LAST phase of the current milestone. Archives the current milestone's artifacts, marks its requirements Complete, and opens the next milestone — **scope pulled directly from JOURNEY.md**, not improvised.
 
 ## When to Use
 
-- After `/qualia-verify N` passes on the LAST phase of a milestone
-- Before starting a v1.5 / v2.0 cycle
+- After `/qualia-verify N` passes on the LAST phase of the current milestone
 - NOT for individual phase completions — use `/qualia-verify N` for that
+- NOT for starting a brand-new project — use `/qualia-new` for that
 
 ## Usage
 
-`/qualia-milestone` — close the current milestone, open the next
+`/qualia-milestone` — close the current milestone, open the next from JOURNEY.md
+`/qualia-milestone --auto` — close + open next, then pause at the milestone boundary to ask "Continue to M{N+1}?" (the one human gate in auto mode beyond initial journey approval)
 
 ## Process
 
 ### 1. Validate Readiness
 
 ```bash
-node ~/.claude/bin/state.js check 2>/dev/null
+node ~/.claude/bin/state.js check
 ```
 
-Check:
-- All phases in STATE.md are `status: verified`
-- `verification: pass` for every phase
-- No open blockers
+`state.js close-milestone` enforces two guards:
+- `MILESTONE_NOT_READY` — any phase not verified
+- `MILESTONE_TOO_SMALL` — milestone has < 2 phases
+
+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).
+
+### 2. Banner + Confirm
 
-If not ready:
 ```bash
-node ~/.claude/bin/qualia-ui.js fail "Milestone not ready — {reason}"
+node ~/.claude/bin/qualia-ui.js banner milestone
+node ~/.claude/bin/qualia-ui.js journey-tree .planning/JOURNEY.md
 ```
-Exit.
 
-### 2. Banner
+The journey-tree shows the user WHERE they are on the ladder before asking the close question. Read `.planning/JOURNEY.md` to find the next milestone's name + scope. Show:
+- Current milestone name + phases completed + requirements delivered
+- Next milestone name + phase sketch + why-now from JOURNEY.md
+
+- header: "Close + open next?"
+- question: "Close {current} and open Milestone {N+1}: {next name}?"
+- options:
+  - "Close + open next" — archive this one, regenerate ROADMAP.md for {next name}
+  - "Pause" — don't close yet
+
+### 3. Archive Current Milestone
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner milestone
+milestone_slug="milestone-{N}-$(echo '{current name}' | tr '[:upper:] ' '[:lower:]-')"
+mkdir -p .planning/archive/$milestone_slug
+
+cp .planning/ROADMAP.md .planning/archive/$milestone_slug/ROADMAP.md
+cp .planning/STATE.md .planning/archive/$milestone_slug/STATE.md
+cp .planning/tracking.json .planning/archive/$milestone_slug/tracking.json
+# Move per-phase artifacts if present
+for f in .planning/phase-*-plan.md .planning/phase-*-verification.md .planning/phase-*-context.md .planning/phase-*-research.md .planning/phase-*-gaps-plan.md; do
+  [ -f "$f" ] && mv "$f" .planning/archive/$milestone_slug/ 2>/dev/null
+done
 ```
 
-### 3. Confirm Closeout
+### 4. Mark Requirements Complete
 
-Show:
-- Milestone name (e.g., "v1 — Launch")
-- Phases completed
-- Requirements delivered
+Edit `.planning/REQUIREMENTS.md`:
+- In the Traceability table, flip this milestone's REQ-IDs from Pending/In Progress → **Complete**
+- Leave the per-milestone section structure intact (preserves history)
 
-- header: "Close milestone?"
-- question: "Close {milestone name} and move to the next milestone?"
-- options:
-  - "Close it" — Archive and open next
-  - "Not yet" — I want to add more first
+### 5. Close Milestone in State Machine
 
-### 4. Archive Current Milestone
+Closes current milestone's counters, appends a summary to `tracking.json` milestones[]:
 
 ```bash
-mkdir -p .planning/archive
-cp .planning/ROADMAP.md .planning/archive/{milestone_slug}-ROADMAP.md
-cp .planning/STATE.md .planning/archive/{milestone_slug}-STATE.md
-cp .planning/tracking.json .planning/archive/{milestone_slug}-tracking.json
-cp -r .planning/phases .planning/archive/{milestone_slug}-phases
+node ~/.claude/bin/state.js close-milestone
 ```
 
-### 5. Update REQUIREMENTS.md
+If all phases are verified and ≥ 2 phases exist, this succeeds without `--force`. Otherwise add `--force` (rare — usually means the user is closing a preview/demo milestone).
+
+### 6. Read Next Milestone From JOURNEY.md
+
+Parse `.planning/JOURNEY.md` to extract the next milestone's:
+- name
+- phase list with goals
+- requirements covered (REQ-IDs)
+- exit criteria
 
-Open `.planning/REQUIREMENTS.md` and:
-- Mark every v1 requirement as Complete in the traceability table
-- Move the `## v1 Requirements` section content to `## Completed (v1)` at the top (for historical reference)
-- Elevate `## v2 Requirements` → `## v1 Requirements` (next milestone's scope)
+If the next milestone is **Handoff** (always the last milestone), use the fixed 4-phase Handoff template (Polish, Content + SEO, Final QA, Handoff) from the journey template.
 
-### 6. Ask About Next Milestone
+If JOURNEY.md doesn't exist (legacy project pre-v4), fall back to asking the user:
 
 - header: "Next milestone"
 - question: "What's the next milestone called?"
-- options (dynamic):
-  - "v1.5 — {suggested name based on v2 requirements}"
-  - "v2.0 — {bigger rewrite}"
-  - "Custom name" — let me type it
 
-### 7. Create New Roadmap
+Then manually sketch its phases. But ideally every v4 project has a JOURNEY.md from the start.
 
-Spawn the roadmapper to create a new ROADMAP.md for the next milestone:
+### 7. Regenerate ROADMAP.md for the New Milestone
+
+Spawn the roadmapper with the next milestone's JOURNEY.md sketch as input:
 
 ```
 Agent(prompt="
 Read your role: @~/.claude/agents/roadmapper.md
 
-<task>
-Create a new ROADMAP.md for the next milestone.
+<mode>next-milestone</mode>
+<journey_file>.planning/JOURNEY.md</journey_file>
+<next_milestone_num>{N+1}</next_milestone_num>
+<next_milestone_name>{next name from JOURNEY.md}</next_milestone_name>
 
-Milestone name: {milestone name}
-Milestone number: {M+1}
+<task>
+Regenerate .planning/ROADMAP.md for Milestone {N+1}. The sketch in JOURNEY.md
+gives you phase names + one-line goals — elevate to full phase-level detail:
+- 2-5 success criteria per phase
+- requirements coverage from REQUIREMENTS.md (section for this milestone)
+- dependency ordering
+
+Do NOT re-plan completed milestones. Do NOT create a new JOURNEY.md — the
+existing one stays the source of truth.
+
+After writing ROADMAP.md, update STATE.md via:
+  node ~/.claude/bin/state.js init --force \\
+    --project '{project}' --client '{client}' --type '{type}' \\
+    --milestone_name '{next name}' \\
+    --phases '<JSON: next milestone phases>' \\
+    --total_phases <count>
+
+--force is needed because a project already exists.
+</task>
+", subagent_type="qualia-roadmapper", description="Open milestone {N+1}")
+```
 
-The new v1 requirements (just promoted from old v2) are in .planning/REQUIREMENTS.md.
-The previous milestone's archive is at .planning/archive/.
+### 8. Commit
 
-Build phases for the new milestone scope. Do NOT plan for already-completed requirements.
-", subagent_type="qualia-roadmapper", description="Create next milestone roadmap")
+```bash
+git add .planning/
+git commit -m "milestone: close M{N} ({current name}) → open M{N+1} ({next name})"
 ```
 
-### 8a. Close Milestone in State Machine
+### 9. Route (auto-chain aware — the milestone boundary is a human gate in auto mode)
 
-Close the current milestone's tracking data before resetting. This preserves lifetime counters (total tasks, phases, milestones completed) across the reset.
+**Case A: this WAS the Handoff milestone closing → project is done.**
 
 ```bash
-node ~/.claude/bin/state.js close-milestone
+node ~/.claude/bin/qualia-ui.js milestone-complete {N} "Handoff" ""
+node ~/.claude/bin/qualia-ui.js end "PROJECT SHIPPED" "/qualia-report"
 ```
 
-### 8b. Reset STATE.md via state.js
+In `--auto` mode, inline-invoke `/qualia-report` and stop. No further chaining — the project is done.
 
-The `init` command resets current-phase fields but preserves `milestone` and `lifetime` data from the close-milestone step above.
+**Case B: a non-final milestone just closed → next milestone is open.**
 
 ```bash
-node ~/.claude/bin/state.js init \
-  --project "{project name}" \
-  --client "{client}" \
-  --type "{type}" \
-  --phases '{JSON from new roadmap}' \
-  --total_phases {new N}
+node ~/.claude/bin/qualia-ui.js milestone-complete {N} "{current name}" "{next name}"
 ```
 
-### 9. Commit
+**In `--auto` mode**, pause here and ask (this is ONE of the two human gates in auto mode, the other being journey approval at `/qualia-new` time):
+
+- header: "Milestone {N} shipped"
+- question: "Continue to Milestone {N+1}: {next name} now?"
+- options:
+  - "Continue" — inline-invoke `/qualia-plan 1 --auto` for the new milestone
+  - "Pause here" — stop and let the user resume later with `/qualia-plan 1 --auto`
+
+If "Continue": the auto-chain resumes. If "Pause": stop, show:
 
 ```bash
-git add .planning/
-git commit -m "feat({milestone_slug}): close milestone, open {next milestone}"
+node ~/.claude/bin/qualia-ui.js end "M{N} CLOSED · M{N+1} READY" "/qualia-plan 1 --auto"
 ```
 
-### 10. Route
+**In guided mode**, always stop and show the next step regardless of position:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "MILESTONE {closed} CLOSED" "/qualia-plan 1"
+node ~/.claude/bin/qualia-ui.js end "M{N} CLOSED · M{N+1} OPEN" "/qualia-plan 1"
 ```
 
 ## What Stays, What Changes
 
 **Stays:**
-- `.planning/PROJECT.md` — the project doesn't change
-- `.planning/archive/` — historical milestones preserved (incl. tracking.json)
-- `tracking.json` lifetime fields — cumulative counters survive across milestones
-- Git history — every commit preserved
+- `.planning/PROJECT.md` — the project identity doesn't change
+- `.planning/JOURNEY.md` — the North Star is the SAME file across all milestones; don't regenerate it
+- `.planning/DESIGN.md` — design system persists
+- `.planning/archive/` — historical milestones preserved
+- `tracking.json` lifetime fields + milestones[] array — cumulative history
 
 **Changes:**
-- `.planning/REQUIREMENTS.md` — Completed section grows, v1 scope shifts
-- `.planning/ROADMAP.md` — new phases for the new milestone
-- `.planning/STATE.md` — reset to Phase 1 of new milestone
+- `.planning/REQUIREMENTS.md` — this milestone's REQ-IDs marked Complete
+- `.planning/ROADMAP.md` — regenerated for the new milestone's phases
+- `.planning/STATE.md` — reset to Phase 1 of the new milestone
 
 **Discarded (but archived):**
-- `.planning/phases/` — the old phase folders move to archive
+- `.planning/phase-*-*.md` files from the closed milestone — moved to archive
 
 ## Rules
 
-1. **Don't close early.** All phases must be `verified` with `pass`. No partial milestones.
-2. **Archive, don't delete.** Old phase work stays accessible via `.planning/archive/`.
-3. **New milestone = new phase numbering.** The next phase is Phase 1 of the new milestone, not Phase {N+1} of the old.
-4. **ERP sync aware.** The ERP reads ROADMAP.md — after milestone close, push to GitHub so the ERP picks up the new phase structure.
+1. **Don't close early.** state.js enforces: all phases verified + ≥ 2 phases, unless `--force`.
+2. **JOURNEY.md is the source of truth for next milestone.** Don't ask the user to name it unless JOURNEY.md is missing (legacy project).
+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.