qualia-framework 2.2.1 → 2.4.1

package/framework/qualia-engine/bin/qualia-tools.js

@@ -99,7 +99,8 @@ function loadConfig(cwd) {
       verifier: get('verifier', { section: 'workflow', field: 'verifier' }) ?? defaults.verifier,
       parallelization,
     };
-  } catch {
+  } catch (e) {
+    process.stderr.write(`WARNING: .planning/config.json is malformed or unreadable, using defaults: ${e.message}\n`);
     return defaults;
   }
 }
@@ -884,8 +885,8 @@ function cmdCommit(cwd, message, files, raw) {
       output(result, raw, 'nothing');
       return;
     }
-    const result = { committed: false, hash: null, reason: 'nothing_to_commit', error: commitResult.stderr };
-    output(result, raw, 'nothing');
+    const result = { committed: false, hash: null, reason: 'commit_failed', error: commitResult.stderr };
+    output(result, raw, 'COMMIT FAILED: ' + (commitResult.stderr || 'unknown error'));
     return;
   }
 
@@ -1156,79 +1157,95 @@ function cmdStateSnapshot(cwd, raw) {
 
   const content = fs.readFileSync(statePath, 'utf-8');
 
-  // Helper to extract **Field:** value patterns
-  const extractField = (fieldName) => {
-    const pattern = new RegExp(`\\*\\*${fieldName}:\\*\\*\\s*(.+)`, 'i');
-    const match = content.match(pattern);
-    return match ? match[1].trim() : null;
-  };
+  // Parse "Phase: X of Y (Name)" or "Phase: X of Y ([Name])"
+  let currentPhase = null, totalPhases = null, currentPhaseName = null;
+  const phaseMatch = content.match(/^Phase:\s*(\d+(?:\.\d+)?)\s*of\s*(\d+)\s*\(([^)]+)\)/m);
+  if (phaseMatch) {
+    currentPhase = phaseMatch[1];
+    totalPhases = parseInt(phaseMatch[2], 10);
+    currentPhaseName = phaseMatch[3].trim();
+  }
+
+  // Parse "Plan: A of B in current phase" or "Plan: Not started" or "Plan: All plans complete"
+  let currentPlan = null, totalPlansInPhase = null;
+  const planMatch = content.match(/^Plan:\s*(\d+)\s*of\s*(\d+)/m);
+  if (planMatch) {
+    currentPlan = planMatch[1];
+    totalPlansInPhase = parseInt(planMatch[2], 10);
+  } else {
+    const planAlt = content.match(/^Plan:\s*(.+)/m);
+    if (planAlt) currentPlan = planAlt[1].trim();
+  }
+
+  // Parse "Status: ..."
+  let status = null;
+  const statusMatch = content.match(/^Status:\s*(.+)/m);
+  if (statusMatch) status = statusMatch[1].trim();
+
+  // Parse "Last activity: DATE — Description"
+  let lastActivity = null, lastActivityDesc = null;
+  const activityMatch = content.match(/^Last activity:\s*(\S+)\s*(?:—|--)\s*(.+)/m);
+  if (activityMatch) {
+    lastActivity = activityMatch[1].trim();
+    lastActivityDesc = activityMatch[2].trim();
+  }
+
+  // Parse "Progress: [...] N%" — extract percentage
+  let progressPercent = null;
+  const progressMatch = content.match(/(\d+)%/);
+  if (progressMatch) progressPercent = parseInt(progressMatch[1], 10);
+
+  // Parse "Assigned to: ..."
+  let assignedTo = null;
+  const assignedMatch = content.match(/^Assigned to:\s*(.+)/m);
+  if (assignedMatch) assignedTo = assignedMatch[1].trim();
 
-  // Extract basic fields
-  const currentPhase = extractField('Current Phase');
-  const currentPhaseName = extractField('Current Phase Name');
-  const totalPhasesRaw = extractField('Total Phases');
-  const currentPlan = extractField('Current Plan');
-  const totalPlansRaw = extractField('Total Plans in Phase');
-  const status = extractField('Status');
-  const progressRaw = extractField('Progress');
-  const lastActivity = extractField('Last Activity');
-  const lastActivityDesc = extractField('Last Activity Description');
-  const pausedAt = extractField('Paused At');
-
-  // Parse numeric fields
-  const totalPhases = totalPhasesRaw ? parseInt(totalPhasesRaw, 10) : null;
-  const totalPlansInPhase = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
-  const progressPercent = progressRaw ? parseInt(progressRaw.replace('%', ''), 10) : null;
-
-  // Extract decisions table
+  // Extract decisions from "### Decisions" section
+  // Format: "- [Phase X]: decision summary" or "- [Pre-roadmap]: decision"
   const decisions = [];
-  const decisionsMatch = content.match(/##\s*Decisions Made[\s\S]*?\n\|[^\n]+\n\|[-|\s]+\n([\s\S]*?)(?=\n##|\n$|$)/i);
-  if (decisionsMatch) {
-    const tableBody = decisionsMatch[1];
-    const rows = tableBody.trim().split('\n').filter(r => r.includes('|'));
-    for (const row of rows) {
-      const cells = row.split('|').map(c => c.trim()).filter(Boolean);
-      if (cells.length >= 3) {
+  const decisionsSection = content.match(/###\s*Decisions\s*\n([\s\S]*?)(?=\n###|\n##|$)/i);
+  if (decisionsSection) {
+    const lines = decisionsSection[1].split('\n');
+    for (const line of lines) {
+      const decMatch = line.match(/^-\s+\[([^\]]+)\]:\s*(.+)/);
+      if (decMatch) {
         decisions.push({
-          phase: cells[0],
-          summary: cells[1],
-          rationale: cells[2],
+          phase: decMatch[1].trim(),
+          summary: decMatch[2].trim(),
+          rationale: '',
         });
       }
     }
   }
 
-  // Extract blockers list
+  // Extract blockers from "### Blockers/Concerns" section
   const blockers = [];
-  const blockersMatch = content.match(/##\s*Blockers\s*\n([\s\S]*?)(?=\n##|$)/i);
-  if (blockersMatch) {
-    const blockersSection = blockersMatch[1];
-    const items = blockersSection.match(/^-\s+(.+)$/gm) || [];
+  const blockersSection = content.match(/###\s*Blockers\/Concerns\s*\n([\s\S]*?)(?=\n###|\n##|$)/i);
+  if (blockersSection) {
+    const items = blockersSection[1].match(/^-\s+(.+)$/gm) || [];
     for (const item of items) {
-      blockers.push(item.replace(/^-\s+/, '').trim());
+      const text = item.replace(/^-\s+/, '').trim();
+      if (text && !text.match(/^none/i)) blockers.push(text);
     }
   }
 
-  // Extract session info
-  const session = {
-    last_date: null,
-    stopped_at: null,
-    resume_file: null,
-  };
-
-  const sessionMatch = content.match(/##\s*Session\s*\n([\s\S]*?)(?=\n##|$)/i);
-  if (sessionMatch) {
-    const sessionSection = sessionMatch[1];
-    const lastDateMatch = sessionSection.match(/\*\*Last Date:\*\*\s*(.+)/i);
-    const stoppedAtMatch = sessionSection.match(/\*\*Stopped At:\*\*\s*(.+)/i);
-    const resumeFileMatch = sessionSection.match(/\*\*Resume File:\*\*\s*(.+)/i);
-
+  // Extract session info from "## Session Continuity"
+  const session = { last_date: null, stopped_at: null, resume_file: null };
+  const sessionSection = content.match(/##\s*Session Continuity\s*\n([\s\S]*?)(?=\n##|$)/i);
+  if (sessionSection) {
+    const sec = sessionSection[1];
+    const lastDateMatch = sec.match(/^Last session:\s*(.+)/m);
+    const stoppedAtMatch = sec.match(/^Stopped at:\s*(.+)/m);
+    const resumeFileMatch = sec.match(/^Resume file:\s*(.+)/m);
     if (lastDateMatch) session.last_date = lastDateMatch[1].trim();
     if (stoppedAtMatch) session.stopped_at = stoppedAtMatch[1].trim();
-    if (resumeFileMatch) session.resume_file = resumeFileMatch[1].trim();
+    if (resumeFileMatch) {
+      const rf = resumeFileMatch[1].trim();
+      session.resume_file = rf.toLowerCase() === 'none' ? null : rf;
+    }
   }
 
-  const result = {
+  output({
     current_phase: currentPhase,
     current_phase_name: currentPhaseName,
     total_phases: totalPhases,
@@ -1238,13 +1255,11 @@ function cmdStateSnapshot(cwd, raw) {
     progress_percent: progressPercent,
     last_activity: lastActivity,
     last_activity_desc: lastActivityDesc,
+    assigned_to: assignedTo,
     decisions,
     blockers,
-    paused_at: pausedAt,
     session,
-  };
-
-  output(result, raw);
+  }, raw);
 }
 
 function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
@@ -2152,6 +2167,32 @@ function main() {
       break;
     }
 
+    case '--help':
+    case 'help': {
+      const cmds = [
+        'state load                — Load project state + config as JSON',
+        'state-snapshot            — Structured snapshot of STATE.md fields',
+        'resolve-model <agent>     — Resolve model for agent from profile',
+        'find-phase <number>       — Find phase directory path',
+        'commit <msg> --files ..   — Commit with planning-aware logic',
+        'verify-summary <path>     — Verify SUMMARY.md completeness',
+        'generate-slug <text>      — Generate URL-safe slug',
+        'current-timestamp         — ISO timestamp',
+        'list-todos [area]         — List pending todos',
+        'verify-path-exists <path> — Check if path exists',
+        'config-ensure-section     — Ensure config section exists',
+        'init <workflow> [args]    — Initialize workflow context',
+        'roadmap get-phase <N>     — Get phase details from ROADMAP.md',
+        'phase-plan-index <N>      — Get plan inventory with wave grouping',
+        'summary-extract <path>    — Extract fields from SUMMARY.md',
+      ];
+      console.log('qualia-tools v2.4.1\n');
+      console.log('Usage: qualia-tools <command> [args] [--raw]\n');
+      console.log('Commands:');
+      cmds.forEach(c => console.log('  ' + c));
+      process.exit(0);
+    }
+
     default:
       error(`Unknown command: ${command}`);
   }

package/framework/qualia-engine/references/continuation-prompt.md

@@ -0,0 +1,97 @@
+# Checkpoint Continuation Prompt Template
+
+Template for spawning a fresh agent to continue execution after a checkpoint pause.
+
+**Why fresh agent:** Resume relies on internal serialization that breaks with parallel tool calls. Fresh agents with explicit state are more reliable.
+
+## Template
+
+```markdown
+<objective>
+Continue executing plan {plan_id} from task {resume_task_number}: {resume_task_name}.
+Previous tasks are already committed. Do NOT re-execute them.
+</objective>
+
+<completed_work>
+## Tasks Already Done
+
+{completed_tasks_table}
+
+These tasks have been committed. Verify their commits exist before continuing:
+```bash
+git log --oneline --all --grep="{plan_id}" | head -10
+```
+</completed_work>
+
+<checkpoint_resolution>
+## Checkpoint Resolution
+
+**Checkpoint type:** {checkpoint_type}
+**User response:** {user_response}
+
+{resume_instructions}
+</checkpoint_resolution>
+
+<resume_from>
+## Resume Point
+
+**Task:** {resume_task_number} — {resume_task_name}
+**Plan path:** {plan_path}
+
+Read the full plan for context, but only execute from task {resume_task_number} onward.
+Follow the same execution rules: per-task commits, deviation handling, verification.
+</resume_from>
+
+<context>
+{state_content}
+{config_content}
+</context>
+
+<success_criteria>
+- [ ] Previous commits verified (not re-executed)
+- [ ] Remaining tasks executed from task {resume_task_number}
+- [ ] Each task committed individually
+- [ ] SUMMARY.md created covering ALL tasks (including pre-checkpoint)
+- [ ] STATE.md updated with final position
+</success_criteria>
+```
+
+## Resume Instructions by Checkpoint Type
+
+### checkpoint:human-verify
+```
+The user has verified the previous work.
+- "approved" → Continue to next task normally.
+- Issue description → Fix the reported issue in the current task context before proceeding.
+```
+
+### checkpoint:decision
+```
+The user selected an option for the decision point.
+- Apply the user's choice: {user_response}
+- This may affect how remaining tasks are implemented.
+- Document the decision in SUMMARY.md under "Decisions Made".
+```
+
+### checkpoint:human-action
+```
+The user completed a manual action (e.g., authentication, external config).
+- "done" → Verify the action succeeded (run verification command if specified).
+- If verification fails, inform user and wait for retry.
+- If verification passes, continue to next task.
+```
+
+## Variables
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `{plan_id}` | Plan frontmatter | e.g., "03-02" |
+| `{resume_task_number}` | Checkpoint return | Task number to resume from |
+| `{resume_task_name}` | Checkpoint return | Name of the resume task |
+| `{completed_tasks_table}` | Checkpoint return | Markdown table of done tasks with commit hashes |
+| `{checkpoint_type}` | Plan XML | human-verify, decision, or human-action |
+| `{user_response}` | User input | What the user provided at the checkpoint |
+| `{resume_instructions}` | This template | Type-specific instructions from above |
+| `{plan_path}` | Phase directory | Path to the PLAN.md file |
+| `{state_content}` | STATE.md | Inlined project state |
+| `{config_content}` | config.json | Inlined project config |

package/framework/qualia-engine/references/employee-guide.md

@@ -0,0 +1,167 @@
+# How Qualia Works — Developer Guide
+
+> This is everything you need to know. Follow the flow, type the commands. The framework handles the rest.
+
+---
+
+## The Big Picture
+
+Every project follows one path:
+
+```
+Start → Build → Polish → Review → PR → Deploy → Handoff
+         70%                    100%
+```
+
+The framework tells you what to do at every step. When in doubt, type `/qualia` — it reads your project state and tells you the exact next command.
+
+---
+
+## Starting a Project
+
+You get assigned a project. Here's what you do:
+
+```
+/qualia-new-project          ← answers questions, sets everything up
+```
+
+This creates a `.planning/` folder with your roadmap, requirements, and phases. You don't need to understand the files — the framework reads them for you.
+
+---
+
+## The Build Cycle (repeat for each phase)
+
+Your roadmap has phases (Phase 1, Phase 2, etc.). For each one:
+
+```
+/qualia-plan-phase 1         ← creates the plan
+/qualia-execute-phase 1      ← builds it
+/qualia-verify-work 1        ← tests it
+```
+
+Then move to the next phase. The framework tells you when to move on.
+
+**Don't memorize this.** After each command finishes, it tells you what's next. Or type `/qualia` anytime.
+
+---
+
+## The Finish Line (this is where most people stall)
+
+When all phases are done, you're about 70% done. The framework now guides you through:
+
+```
+  ✓ Build phases       ← you already did this
+  ✓ Milestone audit    ← framework runs this
+  ✓ Milestone archived ← framework does this
+  ▶ Design polish      ← /critique → /polish → /harden
+  · Code review        ← /qualia-review --web
+  · Pull request       ← /pr
+  · Deploy             ← Fawzi handles this
+  · Client handoff     ← /client-handoff
+```
+
+The framework walks you through each step. Just keep typing `/qualia` to see what's next.
+
+---
+
+## The 10 Commands That Matter
+
+| When | Command | What it does |
+|------|---------|-------------|
+| **Starting** | `/qualia-new-project` | Sets up everything from scratch |
+| **Building** | `/qualia-plan-phase N` | Plans a phase |
+| | `/qualia-execute-phase N` | Builds it |
+| | `/qualia-verify-work N` | Tests it |
+| **Polishing** | `/critique` | Reviews the design |
+| | `/polish` | Fixes spacing, alignment, details |
+| | `/harden` | Handles edge cases, errors, overflow |
+| **Shipping** | `/qualia-review --web` | Code quality + security audit |
+| | `/pr` | Creates a pull request |
+| **Anytime** | `/qualia` | "What should I do next?" |
+
+Everything else is optional. These 10 get the job done.
+
+---
+
+## When You're Stuck
+
+```
+/qualia           ← "what's next?" — reads state, tells you the command
+/qualia-idk       ← "I'm lost" — analyzes everything, suggests a path
+/qualia-debug     ← "something is broken" — structured debugging
+/qualia-progress  ← "where am I?" — full progress report
+```
+
+If none of those help, paste the error and ask Claude directly. If Claude can't fix it, escalate to Fawzi.
+
+---
+
+## Session Start / End
+
+**Every session starts the same way.** Claude automatically runs `/qualia-start` which shows you:
+- What project you're in
+- What branch you're on
+- System health
+- What to do next
+
+**When you're done for the day:**
+```
+/qualia-pause-work    ← saves your context for next time
+/qualia-report        ← logs what you did (Fawzi reviews these)
+```
+
+**When you come back:**
+```
+/qualia-resume-work   ← picks up where you left off
+```
+
+---
+
+## Rules (non-negotiable)
+
+1. **Feature branches only** — never push to main. The framework blocks it automatically.
+2. **Read before write** — don't edit files you haven't read.
+3. **MVP first** — build what's asked, nothing extra.
+4. **Push to GitHub** — you push code. Fawzi deploys to production.
+5. **`/qualia` is your friend** — lost? type it. It always knows what's next.
+
+---
+
+## What the Framework Does Behind the Scenes
+
+You don't need to understand this, but if you're curious:
+
+- **Hooks** run automatically on certain actions (commits, deploys, file writes). They enforce rules like "no pushing to main" and "no editing .env files." If a hook blocks you, it tells you why and how to fix it.
+- **Skills** are the `/commands` you type. They're like recipes — each one does a specific thing.
+- **Agents** are AI workers that skills spawn to do heavy lifting (research, verification, code review). You don't interact with them directly.
+- **`.planning/`** is where the framework tracks everything about your project. Don't edit these files manually — the framework manages them.
+
+---
+
+## Quick Reference Card
+
+```
+◆ QUALIA DEVELOPER FLOW
+
+  /qualia-new-project
+       ↓
+  For each phase:
+    /qualia-plan-phase N
+    /qualia-execute-phase N
+    /qualia-verify-work N
+       ↓
+  /qualia-complete-milestone
+       ↓
+  FINISH LINE:
+    /critique → /polish → /harden
+    /qualia-review --web
+    /pr
+       ↓
+  Fawzi deploys
+       ↓
+  /client-handoff
+       ↓
+  Done.
+
+  Lost? Type /qualia
+```

package/framework/qualia-engine/templates/lab-notes.md

@@ -0,0 +1,16 @@
+# Lab Notes — [Project Name]
+
+> What failed, why it failed, and what worked instead.
+> Read by planners and researchers to avoid repeating dead-end approaches.
+> Updated via `/learn` or manually during debugging sessions.
+
+---
+
+<!-- Entry format:
+### Phase N: [Phase Title]
+
+**Tried:** [approach that was attempted]
+**Failed because:** [root cause — be specific]
+**Better approach:** [what actually worked, or what to try next]
+**Date:** YYYY-MM-DD
+-->

package/framework/qualia-engine/templates/projects/ai-agent.md

@@ -74,7 +74,7 @@
 
 ### Phase 4: Admin Panel
 **Goal:** Admin interface for managing the AI agent: prompts, users, analytics
-**Skills:** [@admin-panel, @supabase]
+**Skills:** [@supabase, @frontend-master]
 **Tasks:**
 - Admin auth (role-based, separate from user auth)
 - System prompt editor (CRUD, version history)

package/framework/qualia-engine/templates/projects/voice-agent.md

@@ -1,8 +1,8 @@
 # Project Template: Voice Agent
 
-> Voice AI agent with Supabase Edge Functions, VAPI/Retell AI, and ElevenLabs.
+> Voice AI agent with Supabase Edge Functions, Retell AI, and ElevenLabs.
 
-**Stack:** Supabase Edge Functions (Deno), VAPI / Retell AI, ElevenLabs, TypeScript
+**Stack:** Supabase Edge Functions (Deno), Retell AI, ElevenLabs, TypeScript
 **Phases:** 6
 **Type:** voice-agent
 
@@ -14,7 +14,7 @@
 **Tasks:**
 - Design Supabase schema: calls, call_events, contacts, tools, system_config
 - Create edge function scaffold (Deno, cors headers, error handling)
-- Configure voice provider (VAPI or Retell AI): API keys, assistant creation
+- Configure Retell AI: API keys, agent creation, ElevenLabs voice selection
 - Environment variables in Supabase (voice provider keys, webhook secret)
 - Basic webhook endpoint that receives and logs call events
 - RLS policies on all tables
@@ -32,7 +32,7 @@
 **Skills:** [@voice-agent]
 **Tasks:**
 - Design conversation flow (state machine: greeting → discovery → action → closing)
-- Create VAPI/Retell assistant configuration (system prompt, voice, language)
+- Create Retell AI agent configuration (system prompt, voice, language)
 - Define conversation states and transitions
 - Slot filling logic (extract key info from conversation)
 - Multi-language support (if applicable — e.g., Greek/English/Russian)

package/framework/qualia-engine/templates/roadmap.md

@@ -113,6 +113,10 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 - Progress table updated by execute workflow
 - Plan count can be "TBD" initially, refined during planning
 
+**FEATURE PHASES ONLY — Do NOT add review, deploy, or handoff phases to the roadmap.**
+
+The finish line system handles polish → review → PR → deploy → handoff automatically after all feature phases are done (`/qualia-complete-milestone` triggers it). Adding them as roadmap phases causes employees to do the work twice.
+
 **Success criteria:**
 - 2-5 observable behaviors per phase (from user's perspective)
 - Cross-checked against requirements during roadmap creation

package/framework/qualia-engine/templates/state.md

@@ -21,6 +21,7 @@ See: .planning/PROJECT.md (updated [date])
 Phase: [X] of [Y] ([Phase name])
 Plan: [A] of [B] in current phase
 Status: [Ready to plan / Planning / Ready to execute / In progress / Phase complete]
+Assigned to: [employee name or "unassigned"]
 Last activity: [YYYY-MM-DD] — [What happened]
 
 Progress: [░░░░░░░░░░] 0%
@@ -69,6 +70,7 @@ None yet.
 ## Session Continuity
 
 Last session: [YYYY-MM-DD HH:MM]
+Last worked by: [employee name]
 Stopped at: [Description of last completed action]
 Resume file: [Path to .continue-here*.md if exists, otherwise "None"]
 ```
@@ -127,6 +129,7 @@ Where we are right now:
 - Phase X of Y — which phase
 - Plan A of B — which plan within phase
 - Status — current state
+- Assigned to — which employee is working on this phase
 - Last activity — what happened most recently
 - Progress bar — visual indicator of overall completion