qualia-framework 2.4.0 → 2.4.2

package/framework/qualia-engine/workflows/progress.md

@@ -12,7 +12,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 **Load progress context:**
 
 ```bash
-INIT=$(node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js init progress)
+INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init progress)
 ```
 
 Extract from init JSON: `project_exists`, `roadmap_exists`, `state_exists`, `phases`, `current_phase`, `next_phase`, `milestone_version`, `completed_count`, `phase_count`, `paused_at`.
@@ -22,18 +22,18 @@ If `project_exists` is false (no `.planning/` directory):
 ```
 No planning structure found.
 
-Run /qualia:new-project to start a new project.
+Run /qualia-new-project to start a new project.
 ```
 
 Exit.
 
-If missing STATE.md: suggest `/qualia:new-project`.
+If missing STATE.md: suggest `/qualia-new-project`.
 
 **If ROADMAP.md missing but PROJECT.md exists:**
 
 This means a milestone was completed and archived. Go to **Route F** (between milestones).
 
-If missing both ROADMAP.md and PROJECT.md: suggest `/qualia:new-project`.
+If missing both ROADMAP.md and PROJECT.md: suggest `/qualia-new-project`.
 </step>
 
 <step name="load">
@@ -71,6 +71,7 @@ If missing both ROADMAP.md and PROJECT.md: suggest `/qualia:new-project`.
 # [Project Name]
 
 **Progress:** [████████░░] 8/10 plans complete
+**Overall:**  [██████░░░░] ~70% to client-ready  {only show if all phases done}
 **Profile:** [quality/balanced/budget]
 
 ## Recent Work
@@ -90,10 +91,10 @@ CONTEXT: [✓ if CONTEXT.md exists | - if not]
 - [any blockers or concerns from STATE.md]
 
 ## Pending Todos
-- [count] pending — /qualia:check-todos to review
+- [count] pending — /qualia-check-todos to review
 
 ## Active Debug Sessions
-- [count] active — /qualia:debug to continue
+- [count] active — /qualia-debug to continue
 (Only show this section if count > 0)
 
 ## What's Next
@@ -152,7 +153,7 @@ Read its `<objective>` section.
 
 **{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md]
 
-`/qualia:execute-phase {phase}`
+`/qualia-execute-phase {phase}`
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -175,7 +176,7 @@ Check if `{phase}-CONTEXT.md` exists in phase directory.
 **Phase {N}: {Name}** — {Goal from ROADMAP.md}
 <sub>✓ Context gathered, ready to plan</sub>
 
-`/qualia:plan-phase {phase-number}`
+`/qualia-plan-phase {phase-number}`
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -191,15 +192,15 @@ Check if `{phase}-CONTEXT.md` exists in phase directory.
 
 **Phase {N}: {Name}** — {Goal from ROADMAP.md}
 
-`/qualia:discuss-phase {phase}` — gather context and clarify approach
+`/qualia-discuss-phase {phase}` — gather context and clarify approach
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
 
 **Also available:**
-- `/qualia:plan-phase {phase}` — skip discussion, plan directly
-- `/qualia:list-phase-assumptions {phase}` — see Claude's assumptions
+- `/qualia-plan-phase {phase}` — skip discussion, plan directly
+- `/qualia-list-phase-assumptions {phase}` — see Claude's assumptions
 
 ---
 ```
@@ -217,15 +218,15 @@ UAT.md exists with gaps (diagnosed issues). User needs to plan fixes.
 
 **{phase}-UAT.md** has {N} gaps requiring fixes.
 
-`/qualia:plan-phase {phase} --gaps`
+`/qualia-plan-phase {phase} --gaps`
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
 
 **Also available:**
-- `/qualia:execute-phase {phase}` — execute phase plans
-- `/qualia:verify-work {phase}` — run more UAT testing
+- `/qualia-execute-phase {phase}` — execute phase plans
+- `/qualia-verify-work {phase}` — run more UAT testing
 
 ---
 ```
@@ -264,46 +265,80 @@ Read ROADMAP.md to get the next phase's name and goal.
 
 **Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
 
-`/qualia:discuss-phase {Z+1}` — gather context and clarify approach
+`/qualia-discuss-phase {Z+1}` — gather context and clarify approach
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
 
 **Also available:**
-- `/qualia:plan-phase {Z+1}` — skip discussion, plan directly
-- `/qualia:verify-work {Z}` — user acceptance test before continuing
+- `/qualia-plan-phase {Z+1}` — skip discussion, plan directly
+- `/qualia-verify-work {Z}` — user acceptance test before continuing
 
 ---
 ```
 
 ---
 
-**Route D: Milestone complete**
+**Route D: Milestone complete (needs archiving)**
 
 ```
 ---
 
-## 🎉 Milestone Complete
+## Milestone phases done!
 
-All {N} phases finished!
+All {N} phases finished. Time to archive.
 
 ## ▶ Next Up
 
-**Complete Milestone** — archive and prepare for next
+**Archive Milestone** — then the finish line begins
 
-`/qualia:complete-milestone`
+`/qualia-complete-milestone`
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
+```
 
-**Also available:**
-- `/qualia:verify-work` — user acceptance test before completing milestone
+---
+
+**Route G: Finish Line (post-milestone, 70% → 100%)**
+
+Check STATE.md for `finish_line` field. If milestone is archived but `finish_line` is not `"complete"`, the project is in the finish line.
+
+```
+---
+
+## ── FINISH LINE ── Getting Client-Ready
+
+Features are built. Now polish, review, and ship.
+
+  ── Progress to Client-Ready ──────────
+  ✓ Build phases       complete
+  ✓ Milestone audit    passed
+  ✓ Milestone archived
+  {▶ or ✓} Design polish      {← you are here | done}
+  {▶ or · or ✓} Code review
+  {▶ or · or ✓} Pull request
+  {· or ✓} Deploy (Fawzi reviews + deploys)
+  {· or ✓} Client handoff
+
+## ▶ Next Up
+
+{Based on finish_line value in STATE.md:}
+  "needs_polish" → `/critique` — then `/polish` then `/harden`
+  "needs_review" → `/qualia-review --web` (or `--ai` for AI/voice projects)
+  "needs_pr"     → `/pr` — create pull request for Fawzi
+  "ready_for_deploy" → "Waiting for Fawzi to review PR and deploy."
+  "deployed"     → `/client-handoff` — prepare delivery document
 
 ---
 ```
 
+**Skip logic for finish line steps:**
+- If project has NO frontend (AI agent, voice agent, edge functions) → skip design polish, set `finish_line: "needs_review"`
+- If finish_line field doesn't exist but milestone is archived → set `finish_line: "needs_polish"` and show Route G
+
 ---
 
 **Route F: Between milestones (ROADMAP.md missing, PROJECT.md exists)**
@@ -323,7 +358,7 @@ Ready to plan the next milestone.
 
 **Start Next Milestone** — questioning → research → requirements → roadmap
 
-`/qualia:new-milestone`
+`/qualia-new-milestone`
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -335,10 +370,10 @@ Ready to plan the next milestone.
 <step name="edge_cases">
 **Handle edge cases:**
 
-- Phase complete but next phase not planned → offer `/qualia:plan-phase [next]`
+- Phase complete but next phase not planned → offer `/qualia-plan-phase [next]`
 - All work complete → offer milestone completion
 - Blockers present → highlight before offering to continue
-- Handoff file exists → mention it, offer `/qualia:resume-work`
+- Handoff file exists → mention it, offer `/qualia-resume-work`
   </step>
 
 </process>
@@ -348,7 +383,7 @@ Ready to plan the next milestone.
 - [ ] Rich context provided (recent work, decisions, issues)
 - [ ] Current position clear with visual progress
 - [ ] What's next clearly explained
-- [ ] Smart routing: /qualia:execute-phase if plans exist, /qualia:plan-phase if not
+- [ ] Smart routing: /qualia-execute-phase if plans exist, /qualia-plan-phase if not
 - [ ] User confirms before any action
 - [ ] Seamless handoff to appropriate qualia command
       </success_criteria>

package/framework/skills/client-handoff/SKILL.md

@@ -107,14 +107,24 @@ git add HANDOFF.md
 git commit -m "docs: add client handoff document"
 ```
 
-### Step 5: Route Next Steps
+### Step 5: Collect Framework Metrics
+
+Auto-collect performance metrics for this project (feeds the `/qualia-evolve` optimization loop):
+
+```bash
+bash ~/.claude/qualia-framework/bin/collect-metrics.sh "$(pwd)"
+```
+
+This is silent — no user interaction needed.
+
+### Step 6: Route Next Steps
 
 After saving, present options:
 
-> "Handoff document saved. Next steps:"
+> "Handoff document saved. Framework metrics collected. Next steps:"
 > - "Share `HANDOFF.md` content with the client (email, PDF, or portal)"
 > - "Run `/qualia-production-check` to verify everything works before handoff"
-> - "Run `/ship` to deploy any final changes first"
+> - "Run `/qualia-evolve` to analyze this project and improve the framework for next time"
 
 ## Guidelines
 

package/framework/skills/deep-research/SKILL.md

@@ -166,82 +166,45 @@ Agent(
 
 ## Phase 3: Synthesize Reports
 
-After all agents return, create a unified report:
+After all 6 agents return, **spawn the synthesizer agent** to consolidate findings. Do NOT synthesize inline — this prevents context bloat in the parent.
 
-```markdown
-# Deep Research Report: [Project Name]
+Each agent's report will be in the tool result. Write each one to a temp file, then spawn the synthesizer:
 
-**Generated:** YYYY-MM-DD
-**Stack:** [Detected stack]
-**Overall Production Readiness:** [Score /100]
-
-## Executive Summary
-[2-3 paragraph synthesis of all findings]
-
-## Critical Issues (Fix Before Production)
-1. [Issue with severity and impact]
-2. ...
-
-## High Priority Improvements
-1. [Improvement with effort estimate]
-2. ...
-
-## Medium Priority Enhancements
-1. [Enhancement with benefit]
-2. ...
-
-## Low Priority / Nice to Have
-1. [Future improvement]
-2. ...
-
----
-
-## Detailed Analysis
-
-### Frontend Architecture
-[Agent 1 findings]
-
-### Backend Architecture
-[Agent 2 findings]
-
-### Database & Data Layer
-[Agent 3 findings]
-
-### Security & DevOps
-[Agent 4 findings]
-
-### Performance & Scalability
-[Agent 5 findings]
-
-### Code Quality & Testing
-[Agent 6 findings]
-
----
-
-## Implementation Roadmap
-
-### Phase 1: Critical Fixes (Week 1)
-- [ ] Task 1
-- [ ] Task 2
-
-### Phase 2: Security Hardening (Week 2)
-- [ ] Task 1
-- [ ] Task 2
-
-### Phase 3: Performance Optimization (Week 3)
-- [ ] Task 1
-- [ ] Task 2
-
-### Phase 4: Code Quality (Ongoing)
-- [ ] Task 1
-- [ ] Task 2
+```bash
+# Write each agent's output to a temp file
+# (use the actual tool result content from each agent)
+```
 
----
+Then spawn the synthesizer agent:
 
-## Resources & References
-- [Relevant best practices docs]
-- [Framework-specific guides]
 ```
+Agent(
+  subagent_type="qualia-research-synthesizer",
+  prompt="
+  Synthesize these specialist reports:
+  - [path to frontend report]
+  - [path to backend report]
+  - [path to database report]
+  - [path to security report]
+  - [path to performance report]
+  - [path to code quality report]
+
+  Downstream consumer: The user needs a prioritized Deep Research Report with:
+  - Overall production readiness score (/100)
+  - Critical/High/Medium/Low severity findings with file:line references
+  - Cross-cutting patterns across all 6 areas
+  - Implementation roadmap grouped by week
+  - Resources and references
+
+  Output path: docs/research/[YYYY-MM-DD]-deep-research.md
+  (also return the full report in your response)
+
+  Do NOT commit.
+  "
+)
+```
+
+The synthesizer handles deduplication, cross-cutting pattern detection, and severity ranking — producing a single unified report.
 
 ## Phase 4: Offer Next Steps
 

package/framework/skills/learn/SKILL.md

@@ -25,28 +25,52 @@ Does this apply beyond the immediate case?
 - Other similar situations where this could happen
 - Related edge cases to watch for
 
-### 4. Classify
+### 4. Classify & Route
 Which category fits best?
+
+**If `.planning/` directory exists in the current project**, also check if this is a **project-level lab note** (a failed approach specific to this project's implementation):
+- Is this about a specific approach that was tried and failed?
+- Is this about a library, API, or pattern that didn't work for THIS project?
+- Would knowing this prevent a planner/researcher from repeating the same dead-end?
+
+If yes → route to **Lab Notes** (see step 5b below).
+
+Otherwise classify as:
 - **Always Rules** — things to always do
 - **Never Rules** — things to never do
 - **Project-Specific Gotchas** — quirks of a specific project
 
-### 5. Propose Rule
+### 5a. Propose Rule (Global)
 Draft rule in this format:
 ```
 - [ALWAYS/NEVER] [specific action] [context/when]
 ```
 
+### 5b. Propose Lab Note (Project-Level)
+Draft lab note in this format:
+```markdown
+### 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:** [today's date]
+```
+
 ### 6. Confirm
-Ask the user if the rule should be added. Do not save without confirmation.
+Ask the user if the rule/lab note should be added. Do not save without confirmation.
 
 ## Output
 
-After user approval, save the rule to **both** locations:
-
+**For global rules** — after user approval, save to **both** locations:
 1. Append to `~/.claude/knowledge/learned-patterns.md` under the appropriate category section
 2. Add to `~/.claude/CLAUDE.md` under "## Learned Patterns" for immediate loading in every session
 
+**For project lab notes** — after user approval:
+1. If `.planning/LAB-NOTES.md` doesn't exist, create it from template at `~/.claude/qualia-framework/templates/lab-notes.md`
+2. Append the lab note entry to `.planning/LAB-NOTES.md`
+3. Do NOT add to global learned-patterns.md (these are project-specific dead-ends, not global rules)
+
 ### 7. Staleness Scan (automatic)
 
 When /learn is invoked, before adding new rules, scan existing patterns:

package/framework/skills/qualia/SKILL.md

@@ -83,8 +83,32 @@ STATE.md exists:
       "All phases complete! Run /qualia-audit-milestone to verify the milestone."
     → If no phases remain AND audit exists AND passed:
       "Milestone audit passed! Run /qualia-complete-milestone to archive and tag."
-    → If milestone is completed:
-      "Milestone complete! Run /client-handoff to prepare the client delivery document."
+
+    ─── FINISH LINE (post-milestone, 70% → 100%) ───
+
+    → If milestone is completed AND no finish_line in STATE.md:
+      Set finish_line: "needs_polish" in STATE.md.
+      "Milestone archived! Now let's get this client-ready."
+      "Features are ~70% of a project. Time for the finish line."
+      Route to: /critique (then /polish, then /harden)
+
+    → If finish_line = "needs_polish":
+      "Run /critique to review the design, then /polish and /harden."
+      (Skip this step if project has no frontend — set finish_line to "needs_review")
+
+    → If finish_line = "needs_review":
+      "Design polished. Now run /qualia-review --web to audit code quality and security."
+
+    → If finish_line = "needs_pr":
+      "Review passed. Push your branch and create a PR:"
+      "Run /pr to create a pull request for Fawzi to review."
+
+    → If finish_line = "ready_for_deploy":
+      "PR created! Fawzi will review and deploy to production."
+      "Once deployed, run /client-handoff to prepare the delivery document."
+
+    → If finish_line = "deployed":
+      "Run /client-handoff to prepare the client delivery document."
 
   blockers exist?
     → Show blockers, ask user how to proceed
@@ -111,28 +135,44 @@ Options:
 
 ## Output Format
 
+**During phases (building features):**
 ```
-## Qualia Status
-
-**Project:** {project_name from PROJECT.md or directory name}
-**Phase:** {N} of {total} - {phase_name}
-**Status:** {status_emoji} {status_description}
+◆ Qualia Status
 
----
+  Project   {name}
+  Phase     {N} of {total} — {phase_name}
+  Status    {status_description}
 
-**Next:** /qualia-{action} {phase}
+  Next → /qualia-{action} {phase}
+```
 
-{If blockers: show them}
-{If decision needed: present options}
+**During finish line (70% → 100%):**
+```
+◆ Qualia Status
+
+  Project   {name}
+  Phases    {total}/{total} complete
+  Stage     FINISH LINE — {step_name}
+
+  ── Progress to Client-Ready ──────────
+  ✓ Build phases       complete
+  ✓ Milestone audit    passed
+  ✓ Milestone archived
+  ▶ Design polish      ← you are here
+  · Code review
+  · Pull request
+  · Deploy (Fawzi)
+  · Client handoff
+
+  Next → /critique
 ```
 
-## Status Emojis
+## Status Markers
 
-- `planning` - Planning phase
-- `executing` - Building
-- `verifying` - Testing
-- `complete` - Done
-- `blocked` - Needs input
+- `✓` — Done
+- `▶` — Current step (you are here)
+- `·` — Not yet
+- `✗` — Failed / blocked
 
 ## Quick Actions
 

package/framework/skills/qualia-complete-milestone/SKILL.md

@@ -100,13 +100,35 @@ git commit -m "milestone: complete v{version}"
 git tag v{version}
 ```
 
-### 9. Offer Next Steps
+### 9. Enter Finish Line
 
-> "Milestone v{version} complete and tagged! Options:"
-> - "Prepare client handoff: `/client-handoff`" — generates client-facing deliverable document
-> - "Ship to production: `/ship`"
-> - "Start next milestone: `/qualia-new-milestone`"
-> - "Run final production audit: `/qualia-production-check`"
+Set `finish_line: "needs_polish"` in STATE.md (or `"needs_review"` if the project has no frontend).
+
+Then show the finish line checklist:
+
+```
+◆ Milestone v{version} archived and tagged!
+
+  Features are ~70% of a project. Time for the finish line.
+
+  ── Progress to Client-Ready ──────────
+  ✓ Build phases       complete
+  ✓ Milestone audit    passed
+  ✓ Milestone archived
+  ▶ Design polish      ← you are here
+  · Code review
+  · Pull request
+  · Deploy (Fawzi reviews + deploys)
+  · Client handoff
+
+  Next → /critique
+```
+
+**For projects without frontend** (AI agents, voice agents, edge functions):
+- Skip design polish step
+- Set `finish_line: "needs_review"` and show `▶ Code review` instead
+
+**Do NOT offer `/client-handoff` or `/ship` directly** — the finish line routing in `/qualia` will guide them through each step in order.
 
 ---
-> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help`
+> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help` · Done for today? Type `/qualia-report`