qualia-framework 3.2.1 → 3.3.1

package/bin/install.js

@@ -81,6 +81,68 @@ function copy(src, dest) {
   fs.copyFileSync(src, dest);
 }
 
+// Recursively copy a directory tree from src to dest.
+// Skips hidden files (dot-prefixed) to avoid syncing .DS_Store, editor temp files, etc.
+function copyTree(src, dest) {
+  if (!fs.existsSync(src)) return;
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.name.startsWith(".")) continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyTree(srcPath, destPath);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// Surgically remove orphaned v2.6 install cruft from ~/.claude/ on upgrade.
+// v2.6 installed a separate ~/.claude/qualia-framework/ directory with workflows/,
+// references/, assets/, bin/qualia-tools.js. v3 doesn't use any of that — it was
+// just never cleaned up. Also removes broken qualia-*.md agents from the v2.6 era
+// that reference /home/qualia/ paths which don't exist.
+function cleanupLegacyV26() {
+  const removed = { dirs: [], files: [] };
+
+  // Remove the entire v2.6 framework leftover directory.
+  const v26Dir = path.join(CLAUDE_DIR, "qualia-framework");
+  try {
+    if (fs.existsSync(v26Dir)) {
+      const versionFile = path.join(v26Dir, "VERSION");
+      // Safety: only remove if it has the v2.6 shape (VERSION file exists)
+      if (fs.existsSync(versionFile)) {
+        fs.rmSync(v26Dir, { recursive: true, force: true });
+        removed.dirs.push("~/.claude/qualia-framework/ (v2.6 leftover)");
+      }
+    }
+  } catch {}
+
+  // Remove broken v2.6 agent files that reference /home/qualia/ paths.
+  // The canonical v3 agents ship with the framework (planner.md, builder.md, etc.)
+  // — scan all qualia-*.md files in agents/ and remove any that contain the
+  // /home/qualia/ signature (v2.6 broken absolute paths).
+  const agentsDest = path.join(CLAUDE_DIR, "agents");
+  try {
+    if (fs.existsSync(agentsDest)) {
+      for (const name of fs.readdirSync(agentsDest)) {
+        if (!name.startsWith("qualia-") || !name.endsWith(".md")) continue;
+        const p = path.join(agentsDest, name);
+        try {
+          const content = fs.readFileSync(p, "utf8");
+          if (content.includes("/home/qualia/.claude")) {
+            fs.unlinkSync(p);
+            removed.files.push(`agents/${name}`);
+          }
+        } catch {}
+      }
+    }
+  } catch {}
+
+  return removed;
+}
+
 // ─── Branded Header ─────────────────────────────────────
 const BOLD = "\x1b[1m";
 const TEAL_GLOW = "\x1b[38;2;0;170;175m";
@@ -227,20 +289,54 @@ async function main() {
     }
   }
 
-  // ─── Templates ─────────────────────────────────────────
+  // ─── Templates (recursive — supports nested projects/ and research-project/) ─
   printSection("Templates");
   const tmplDir = path.join(FRAMEWORK_DIR, "templates");
   const tmplDest = path.join(CLAUDE_DIR, "qualia-templates");
   if (!fs.existsSync(tmplDest)) fs.mkdirSync(tmplDest, { recursive: true });
-  for (const file of fs.readdirSync(tmplDir)) {
+  for (const entry of fs.readdirSync(tmplDir, { withFileTypes: true })) {
+    if (entry.name.startsWith(".")) continue;
+    const srcPath = path.join(tmplDir, entry.name);
+    const destPath = path.join(tmplDest, entry.name);
     try {
-      copy(path.join(tmplDir, file), path.join(tmplDest, file));
-      ok(file);
+      if (entry.isDirectory()) {
+        copyTree(srcPath, destPath);
+        ok(`${entry.name}/ (directory)`);
+      } else {
+        copy(srcPath, destPath);
+        ok(entry.name);
+      }
     } catch (e) {
-      warn(`${file} — ${e.message}`);
+      warn(`${entry.name} — ${e.message}`);
     }
   }
 
+  // ─── References (methodology docs loaded by skills at runtime) ────
+  printSection("References");
+  const refDir = path.join(FRAMEWORK_DIR, "references");
+  const refDest = path.join(CLAUDE_DIR, "qualia-references");
+  if (fs.existsSync(refDir)) {
+    if (!fs.existsSync(refDest)) fs.mkdirSync(refDest, { recursive: true });
+    for (const file of fs.readdirSync(refDir)) {
+      try {
+        copy(path.join(refDir, file), path.join(refDest, file));
+        ok(file);
+      } catch (e) {
+        warn(`${file} — ${e.message}`);
+      }
+    }
+  } else {
+    log(`${DIM}(no references/ in framework — skipping)${RESET}`);
+  }
+
+  // ─── Cleanup legacy v2.6 install cruft ────────────────────
+  const legacy = cleanupLegacyV26();
+  if (legacy.dirs.length > 0 || legacy.files.length > 0) {
+    printSection("Cleanup (v2.6 leftover)");
+    for (const d of legacy.dirs) ok(`removed ${d}`);
+    for (const f of legacy.files) ok(`removed ${f}`);
+  }
+
   // ─── CLAUDE.md with role ───────────────────────────────
   printSection("Configuration");
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "3.2.1",
+  "version": "3.3.1",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -32,6 +32,7 @@
     "rules/",
     "skills/",
     "templates/",
+    "references/",
     "tests/",
     "docs/",
     "CLAUDE.md",

package/references/questioning.md

@@ -0,0 +1,123 @@
+# Questioning Guide
+
+Project initialization is dream extraction, not requirements gathering. Help the user discover and articulate what they want. Collaborate, don't interrogate.
+
+## Philosophy
+
+**You are a thinking partner.**
+
+The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
+
+Don't follow a script. Follow the thread.
+
+## The Goal
+
+By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
+
+- **Research** needs: what domain, what the user already knows, what unknowns exist
+- **Requirements** needs: clear vision to scope v1 features
+- **Roadmap** needs: clear vision to decompose into phases, what "done" looks like
+- **Plan-phase** needs: specific requirements to break into tasks
+- **Execute-phase** needs: success criteria to verify against
+
+A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
+
+## How to Question
+
+**Start open.** Let them dump their mental model. Don't interrupt with structure.
+
+**Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
+
+**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
+
+**Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
+
+**Clarify ambiguity.** "When you say Z, do you mean A or B?"
+
+**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
+
+## Question Types
+
+Use as inspiration, not a checklist. Pick what's relevant to the thread.
+
+### Motivation — why this exists
+
+- "What prompted this?"
+- "What are you doing today that this replaces?"
+- "What would you do if this existed?"
+
+### Concreteness — what it actually is
+
+- "Walk me through using this"
+- "You said X — what does that actually look like?"
+- "Give me an example"
+
+### Clarification — what they mean
+
+- "When you say Z, do you mean A or B?"
+- "You mentioned X — tell me more about that"
+
+### Success — how you'll know it's working
+
+- "How will you know this is working?"
+- "What does done look like?"
+
+## Using AskUserQuestion
+
+Present concrete options the user can react to.
+
+**Good options:**
+- Interpretations of what they might mean
+- Specific examples to confirm or deny
+- Concrete choices that reveal priorities
+
+**Bad options:**
+- Generic categories ("Technical", "Business", "Other")
+- Leading options that presume an answer
+- Too many options (2-4 is ideal)
+
+**Example — vague answer "it should be fast":**
+
+- header: "Fast"
+- question: "Fast how?"
+- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
+
+**Example — following a thread "frustrated with current tools":**
+
+- header: "Frustration"
+- question: "What specifically frustrates you?"
+- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
+
+## Context Checklist
+
+Mental checklist, not conversation structure. Check as you go; weave questions naturally.
+
+- [ ] What they're building (concrete enough to explain to a stranger)
+- [ ] Why it needs to exist (the problem or desire driving it)
+- [ ] Who it's for (even if just themselves)
+- [ ] What "done" looks like (observable outcomes)
+
+Four things. If they volunteer more, capture it.
+
+## Decision Gate
+
+When you could write a clear PROJECT.md:
+
+- header: "Ready?"
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+  - "Create PROJECT.md" — Let's move forward
+  - "Keep exploring" — I want to share more / ask me more
+
+If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally. Loop until approved.
+
+## Anti-Patterns
+
+- **Checklist walking** — Going through domains regardless of what they said
+- **Canned questions** — "What's your core value?" regardless of context
+- **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
+- **Interrogation** — Firing questions without building on answers
+- **Rushing** — Minimizing questions to get to "the work"
+- **Shallow acceptance** — Taking vague answers without probing
+- **Premature constraints** — Asking about tech stack before understanding the idea
+- **User skills** — NEVER ask about user's technical experience. Claude builds.

package/skills/qualia-discuss/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: qualia-discuss
+description: "Capture phase decisions, trade-offs, and constraints BEFORE planning. Use for complex phases with regulatory, compliance, or architectural stakes. Creates .planning/phase-{N}-context.md that planner honors as locked input."
+---
+
+# /qualia-discuss — Phase Context Capture
+
+Before a complex phase gets planned, surface the decisions and trade-offs that must inform planning. Output: `.planning/phase-{N}-context.md` that the planner reads as locked input.
+
+## When to Use
+
+- Regulated domains (legal, medical, financial) where wrong choices have legal cost
+- Phases with architectural forks (e.g., "auth via middleware or RLS?")
+- Phases with external dependencies you want to lock first
+- Anytime the user says "wait, let's think about this one"
+
+## Process
+
+### 1. Determine Phase
+
+```bash
+node ~/.claude/bin/state.js check 2>/dev/null
+```
+
+If a phase number was passed as argument, use it. Otherwise use the current phase from STATE.md.
+
+### 2. Load Context
+
+```bash
+cat .planning/PROJECT.md 2>/dev/null
+cat .planning/ROADMAP.md 2>/dev/null
+cat .planning/research/SUMMARY.md 2>/dev/null
+```
+
+Identify:
+- Phase goal from ROADMAP.md
+- Requirements covered by this phase
+- Research flags for this phase (from SUMMARY.md)
+
+### 3. Open the Conversation
+
+Print the banner:
+```bash
+node ~/.claude/bin/qualia-ui.js banner discuss {N} "{phase name from ROADMAP.md}"
+```
+
+Ask inline (free text, not AskUserQuestion):
+
+**"We're about to plan {phase name}. The goal is: {goal from ROADMAP.md}. Before I hand this to the planner, what decisions, trade-offs, or constraints should be locked in?"**
+
+Wait for their response.
+
+### 4. Follow the Thread
+
+Based on their answer, dig into specifics:
+
+- If they mention a technology → "Why that one specifically?"
+- If they mention a constraint → "What happens if we don't honor this?"
+- If they mention a trade-off → "Which side do you want to land on, and why?"
+- If they mention a concern → "What's the worst case?"
+
+Use `AskUserQuestion` when there are clear interpretation forks. Free text otherwise.
+
+### 5. Capture Locked Decisions
+
+Build up a list of **locked decisions** — things the planner MUST honor. Each decision has:
+- The choice (what)
+- The rationale (why)
+- The source (who/when)
+
+Also capture:
+- **Discretion items** — things the planner can decide freely
+- **Deferred ideas** — good ideas that are NOT in this phase
+- **Risk flags** — things to watch during building
+- **Open questions** — things that still need resolution
+
+### 6. Decision Gate
+
+When you have enough context:
+
+- header: "Ready to lock?"
+- question: "Ready to lock these decisions and move to /qualia-plan {N}?"
+- options:
+  - "Lock it in" — Write phase-{N}-context.md and done
+  - "Keep exploring" — I have more to say
+
+Loop until "Lock it in".
+
+### 7. Write phase-{N}-context.md
+
+Use the template at `~/.claude/qualia-templates/phase-context.md`. Fill every section with concrete content.
+
+```bash
+# Write the file to .planning/phase-{N}-context.md
+```
+
+### 8. Commit
+
+```bash
+git add .planning/phase-{N}-context.md
+git commit -m "docs(phase-{N}): capture phase context before planning"
+```
+
+### 9. Route to Next
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "PHASE {N} CONTEXT LOCKED" "/qualia-plan {N}"
+```
+
+## Rules
+
+1. **One session, one phase.** Don't try to discuss phases 1 and 2 in the same invocation.
+2. **Locked decisions are NON-NEGOTIABLE.** The planner will honor them exactly. If you lock something you're not sure about, that's a mistake.
+3. **Don't redo research.** If the user asks a research question you don't know, suggest `/qualia-research {N}` instead.
+4. **Short context files are fine.** If the phase is simple, a 30-line context.md is better than a forced 200-line one.

package/skills/qualia-map/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: qualia-map
+description: "Map an existing codebase to infer architecture, stack, conventions, and what's already built. For brownfield projects — run BEFORE /qualia-new so Validated requirements get inferred from existing code."
+---
+
+# /qualia-map — Codebase Mapping (Brownfield)
+
+Scans an existing repo and produces `.planning/codebase/` — architecture, stack, conventions, concerns. Used by `/qualia-new` to infer what's already built and seed Validated requirements.
+
+## When to Use
+
+- Taking over an existing client project
+- Adding features to a repo you didn't build
+- Before `/qualia-new` on any directory that already has code
+
+## Usage
+
+`/qualia-map` — scan the current working directory
+
+## Process
+
+### 1. Check for Existing Code
+
+```bash
+ls -la 2>/dev/null
+test -f package.json && echo "HAS_PACKAGE"
+test -d .git && echo "HAS_GIT"
+test -d .planning/codebase && echo "ALREADY_MAPPED"
+```
+
+If `ALREADY_MAPPED`, ask:
+- header: "Re-map?"
+- question: "Codebase already mapped. Re-scan?"
+- options:
+  - "Re-scan" — overwrite existing map
+  - "Skip" — use existing map
+
+### 2. Banner
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner map
+```
+
+### 3. Spawn Parallel Mapper Agents
+
+Map 4 dimensions in parallel for speed. Each writes one file in `.planning/codebase/`:
+
+```
+Agent 1: Architecture scanner
+  Task(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="
+  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="
+  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="
+  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).
+  Produce .planning/codebase/concerns.md.
+  ", subagent_type="general-purpose", description="Concerns scan")
+```
+
+### 4. Wait for All 4
+
+After all 4 agents complete, read the 4 output files.
+
+### 5. Synthesize
+
+Create `.planning/codebase/README.md` — one-page summary linking to the 4 dimension files.
+
+```markdown
+# Codebase Map
+
+**Scanned:** {date}
+**Repo:** {name}
+**LOC:** {lines of code from wc -l}
+
+## At a Glance
+
+- **Stack:** {from stack.md — one line}
+- **Architecture:** {from architecture.md — one sentence}
+- **Conventions:** {from conventions.md — one sentence}
+- **Concerns:** {count of concerns found}
+
+## Validated Capabilities (Inferred)
+
+Based on existing code, this project already does:
+- {capability 1} (evidence: {file path})
+- {capability 2} (evidence: {file path})
+- {capability 3} (evidence: {file path})
+
+These become **Validated requirements** in PROJECT.md when `/qualia-new` runs.
+
+## Dimension Details
+
+- [Architecture](./architecture.md)
+- [Stack](./stack.md)
+- [Conventions](./conventions.md)
+- [Concerns](./concerns.md)
+```
+
+### 6. Commit
+
+```bash
+git add .planning/codebase/
+git commit -m "docs: map existing codebase"
+```
+
+### 7. Route
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "CODEBASE MAPPED" "/qualia-new"
+```
+
+## What `/qualia-new` Does With This
+
+When `/qualia-new` runs AFTER `/qualia-map`, it:
+1. Reads `.planning/codebase/README.md`
+2. Extracts Validated capabilities
+3. Pre-populates PROJECT.md with Validated requirements section
+4. Skips questions about things already built
+5. Focuses questioning on NEW capabilities being added
+
+## Rules
+
+1. **Non-destructive.** This skill only READS code, never modifies it.
+2. **Four parallel agents.** Don't sequential-scan — parallel is ~4x faster.
+3. **Dimension files are structured.** The orchestrator downstream (`/qualia-new`) reads them programmatically.
+4. **Concerns ≠ fixes.** This skill documents concerns. It does NOT fix them. Use `/qualia-optimize` for that.

package/skills/qualia-milestone/SKILL.md

@@ -0,0 +1,148 @@
+---
+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."
+---
+
+# /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.
+
+## When to Use
+
+- After `/qualia-verify N` passes on the LAST phase of a milestone
+- Before starting a v1.5 / v2.0 cycle
+- NOT for individual phase completions — use `/qualia-verify N` for that
+
+## Usage
+
+`/qualia-milestone` — close the current milestone, open the next
+
+## Process
+
+### 1. Validate Readiness
+
+```bash
+node ~/.claude/bin/state.js check 2>/dev/null
+```
+
+Check:
+- All phases in STATE.md are `status: verified`
+- `verification: pass` for every phase
+- No open blockers
+
+If not ready:
+```bash
+node ~/.claude/bin/qualia-ui.js fail "Milestone not ready — {reason}"
+```
+Exit.
+
+### 2. Banner
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner milestone
+```
+
+### 3. Confirm Closeout
+
+Show:
+- Milestone name (e.g., "v1 — Launch")
+- Phases completed
+- Requirements delivered
+
+- 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
+
+### 4. Archive Current Milestone
+
+```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 -r .planning/phases .planning/archive/{milestone_slug}-phases
+```
+
+### 5. Update REQUIREMENTS.md
+
+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)
+
+### 6. Ask About Next Milestone
+
+- 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
+
+Spawn the roadmapper to create a new ROADMAP.md for the next milestone:
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/roadmapper.md
+
+<task>
+Create a new ROADMAP.md for the next milestone.
+
+Milestone name: {milestone name}
+Milestone number: {M+1}
+
+The new v1 requirements (just promoted from old v2) are in .planning/REQUIREMENTS.md.
+The previous milestone's archive is at .planning/archive/.
+
+Build phases for the new milestone scope. Do NOT plan for already-completed requirements.
+", subagent_type="qualia-roadmapper", description="Create next milestone roadmap")
+```
+
+### 8. Reset STATE.md via state.js
+
+```bash
+node ~/.claude/bin/state.js init \
+  --project "{project name}" \
+  --client "{client}" \
+  --type "{type}" \
+  --phases '{JSON from new roadmap}' \
+  --total_phases {new N}
+```
+
+### 9. Commit
+
+```bash
+git add .planning/
+git commit -m "feat({milestone_slug}): close milestone, open {next milestone}"
+```
+
+### 10. Route
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "MILESTONE {closed} CLOSED" "/qualia-plan 1"
+```
+
+## What Stays, What Changes
+
+**Stays:**
+- `.planning/PROJECT.md` — the project doesn't change
+- `.planning/archive/` — historical milestones preserved
+- Git history — every commit preserved
+
+**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
+
+**Discarded (but archived):**
+- `.planning/phases/` — the old phase folders move 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.