qualia-framework 2.6.0 → 3.1.0

package/framework/qualia-framework/workflows/verify-work.md

@@ -1,625 +0,0 @@
-<purpose>
-Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /clear, and feeds gaps into /qualia:plan-phase --gaps.
-
-User tests, Claude records. One test at a time. Plain text responses.
-</purpose>
-
-<philosophy>
-**Show expected, ask if reality matches.**
-
-Claude presents what SHOULD happen. User confirms or describes what's different.
-- "yes" / "y" / "next" / empty → pass
-- Anything else → logged as issue, severity inferred
-
-No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. Does it?"
-</philosophy>
-
-<template>
-@/home/qualia/.claude/qualia-framework/templates/UAT.md
-</template>
-
-<process>
-
-<step name="initialize" priority="first">
-If $ARGUMENTS contains a phase number, load context:
-
-```bash
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init verify-work "${PHASE_ARG}")
-```
-
-Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`.
-</step>
-
-<step name="check_active_session">
-**First: Check for active UAT sessions**
-
-```bash
-find .planning/phases -name "*-UAT.md" -type f 2>/dev/null | head -5
-```
-
-**If active sessions exist AND no $ARGUMENTS provided:**
-
-Read each file's frontmatter (status, phase) and Current Test section.
-
-Display inline:
-
-```
-## Active UAT Sessions
-
-| # | Phase | Status | Current Test | Progress |
-|---|-------|--------|--------------|----------|
-| 1 | 04-comments | testing | 3. Reply to Comment | 2/6 |
-| 2 | 05-auth | testing | 1. Login Form | 0/4 |
-
-Reply with a number to resume, or provide a phase number to start new.
-```
-
-Wait for user response.
-
-- If user replies with number (1, 2) → Load that file, go to `resume_from_file`
-- If user replies with phase number → Treat as new session, go to `create_uat_file`
-
-**If active sessions exist AND $ARGUMENTS provided:**
-
-Check if session exists for that phase. If yes, offer to resume or restart.
-If no, continue to `create_uat_file`.
-
-**If no active sessions AND no $ARGUMENTS:**
-
-```
-No active UAT sessions.
-
-Provide a phase number to start testing (e.g., /qualia:verify-work 4)
-```
-
-**If no active sessions AND $ARGUMENTS provided:**
-
-Continue to `create_uat_file`.
-</step>
-
-<step name="run_automated_tests">
-**Run automated tests before manual UAT:**
-
-Follow the canonical test detection and execution from `~/.claude/skills/test-runner/SKILL.md` (Run Tests section).
-
-**If tests fail:**
-
-Present to user:
-```
-⚠ {N} automated test(s) failed. These should be fixed before manual UAT.
-
-Failed tests:
-{list}
-
-Options:
-1. Fix tests first (recommended) — exit and fix, then re-run /qualia:verify-work
-2. Continue to manual UAT anyway — test failures will be noted in UAT.md
-```
-
-Use AskUserQuestion with those 2 options.
-
-If "Fix tests first": Exit with guidance.
-If "Continue": Note failures in UAT.md header and proceed to find_summaries.
-
-**If no test infrastructure detected:**
-
-Skip silently — proceed to find_summaries.
-</step>
-
-<step name="find_summaries">
-**Find what to test:**
-
-Use `phase_dir` from init (or run init if not already done).
-
-```bash
-ls "$phase_dir"/*-SUMMARY.md 2>/dev/null
-```
-
-Read each SUMMARY.md to extract testable deliverables.
-</step>
-
-<step name="extract_tests">
-**Extract testable deliverables from SUMMARY.md:**
-
-Parse for:
-1. **Accomplishments** - Features/functionality added
-2. **User-facing changes** - UI, workflows, interactions
-
-Focus on USER-OBSERVABLE outcomes, not implementation details.
-
-For each deliverable, create a test:
-- name: Brief test name
-- expected: What the user should see/experience (specific, observable)
-
-Examples:
-- Accomplishment: "Added comment threading with infinite nesting"
-  → Test: "Reply to a Comment"
-  → Expected: "Clicking Reply opens inline composer below comment. Submitting shows reply nested under parent with visual indentation."
-
-Skip internal/non-observable items (refactors, type changes, etc.).
-</step>
-
-<step name="create_uat_file">
-**Create UAT file with all tests:**
-
-```bash
-mkdir -p "$PHASE_DIR"
-```
-
-Build test list from extracted deliverables.
-
-Create file:
-
-```markdown
----
-status: testing
-phase: XX-name
-source: [list of SUMMARY.md files]
-started: [ISO timestamp]
-updated: [ISO timestamp]
----
-
-## Current Test
-<!-- OVERWRITE each test - shows where we are -->
-
-number: 1
-name: [first test name]
-expected: |
-  [what user should observe]
-awaiting: user response
-
-## Tests
-
-### 1. [Test Name]
-expected: [observable behavior]
-result: [pending]
-
-### 2. [Test Name]
-expected: [observable behavior]
-result: [pending]
-
-...
-
-## Summary
-
-total: [N]
-passed: 0
-issues: 0
-pending: [N]
-skipped: 0
-
-## Gaps
-
-[none yet]
-```
-
-Write to `.planning/phases/XX-name/{phase}-UAT.md`
-
-Proceed to `present_test`.
-</step>
-
-<step name="present_test">
-**Present current test to user:**
-
-Read Current Test section from UAT file.
-
-Display using checkpoint box format:
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  CHECKPOINT: Verification Required                           ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Test {number}: {name}**
-
-{expected}
-
-──────────────────────────────────────────────────────────────
-→ Type "pass" or describe what's wrong
-──────────────────────────────────────────────────────────────
-```
-
-Wait for user response (plain text, no AskUserQuestion).
-</step>
-
-<step name="process_response">
-**Process user response and update file:**
-
-**If response indicates pass:**
-- Empty response, "yes", "y", "ok", "pass", "next", "approved", "✓"
-
-Update Tests section:
-```
-### {N}. {name}
-expected: {expected}
-result: pass
-```
-
-**If response indicates skip:**
-- "skip", "can't test", "n/a"
-
-Update Tests section:
-```
-### {N}. {name}
-expected: {expected}
-result: skipped
-reason: [user's reason if provided]
-```
-
-**If response is anything else:**
-- Treat as issue description
-
-Infer severity from description:
-- Contains: crash, error, exception, fails, broken, unusable → blocker
-- Contains: doesn't work, wrong, missing, can't → major
-- Contains: slow, weird, off, minor, small → minor
-- Contains: color, font, spacing, alignment, visual → cosmetic
-- Default if unclear: major
-
-Update Tests section:
-```
-### {N}. {name}
-expected: {expected}
-result: issue
-reported: "{verbatim user response}"
-severity: {inferred}
-```
-
-Append to Gaps section (structured YAML for plan-phase --gaps):
-```yaml
-- truth: "{expected behavior from test}"
-  status: failed
-  reason: "User reported: {verbatim user response}"
-  severity: {inferred}
-  test: {N}
-  artifacts: []  # Filled by diagnosis
-  missing: []    # Filled by diagnosis
-```
-
-**After any response:**
-
-Update Summary counts.
-Update frontmatter.updated timestamp.
-
-If more tests remain → Update Current Test, go to `present_test`
-If no more tests → Go to `complete_session`
-</step>
-
-<step name="resume_from_file">
-**Resume testing from UAT file:**
-
-Read the full UAT file.
-
-Find first test with `result: [pending]`.
-
-Announce:
-```
-Resuming: Phase {phase} UAT
-Progress: {passed + issues + skipped}/{total}
-Issues found so far: {issues count}
-
-Continuing from Test {N}...
-```
-
-Update Current Test section with the pending test.
-Proceed to `present_test`.
-</step>
-
-<step name="complete_session">
-**Complete testing and commit:**
-
-Update frontmatter:
-- status: complete
-- updated: [now]
-
-Clear Current Test section:
-```
-## Current Test
-
-[testing complete]
-```
-
-Commit the UAT file:
-```bash
-node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "test({phase}): complete UAT - {passed} passed, {issues} issues" --files ".planning/phases/XX-name/{phase}-UAT.md"
-```
-
-Present summary:
-```
-## UAT Complete: Phase {phase}
-
-| Result | Count |
-|--------|-------|
-| Passed | {N}   |
-| Issues | {N}   |
-| Skipped| {N}   |
-
-[If issues > 0:]
-### Issues Found
-
-[List from Issues section]
-```
-
-**If issues > 0:** Proceed to `diagnose_issues`
-
-**If issues == 0:**
-
-**Frontend design quality check:**
-
-Detect if this phase includes frontend work:
-```bash
-# Check phase PLAN.md files for frontend signals
-grep -rlE '\.(tsx|css|scss)|components/|app/page|app/layout|Tailwind|className' "$PHASE_DIR"/*-PLAN.md 2>/dev/null && echo "HAS_FRONTEND=true" || echo "HAS_FRONTEND=false"
-```
-
-Also check if phase name/objective contains: UI, frontend, design, component, page, layout, dashboard, form, landing, hero.
-
-**If HAS_FRONTEND=true AND issues == 0:**
-
-```
-All tests passed. This phase includes frontend work.
-
-### Design Quality (recommended before moving on)
-
-1. `/critique` — Design director review (catches AI slop, visual hierarchy issues)
-2. `/polish` — Detail pass (spacing, alignment, consistency)
-3. `/harden` — Edge cases, overflow, i18n robustness
-
-Skip? Just run the next command directly. Otherwise run `/critique` now.
-```
-
-**If HAS_FRONTEND=false:**
-```
-All tests passed. Ready to continue.
-
-- `/clear` then `/qualia:plan-phase {next}` — Plan next phase
-- `/clear` then `/qualia:execute-phase {next}` — Execute next phase
-```
-</step>
-
-<step name="diagnose_issues">
-**Diagnose root causes before planning fixes:**
-
-```
----
-
-{N} issues found. Diagnosing root causes...
-
-Spawning parallel debug agents to investigate each issue.
-```
-
-- Load diagnose-issues workflow
-- Follow @/home/qualia/.claude/qualia-framework/workflows/diagnose-issues.md
-- Spawn parallel debug agents for each issue
-- Collect root causes
-- Update UAT.md with root causes
-- Proceed to `plan_gap_closure`
-
-Diagnosis runs automatically - no user prompt. Parallel agents investigate simultaneously, so overhead is minimal and fixes are more accurate.
-</step>
-
-<step name="plan_gap_closure">
-**Auto-plan fixes from diagnosed gaps:**
-
-Display:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► PLANNING FIXES
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning planner for gap closure...
-```
-
-Spawn qualia-planner in --gaps mode:
-
-```
-Task(
-  prompt="""
-<planning_context>
-
-**Phase:** {phase_number}
-**Mode:** gap_closure
-
-**UAT with diagnoses:**
-@.planning/phases/{phase_dir}/{phase}-UAT.md
-
-**Project State:**
-@.planning/STATE.md
-
-**Roadmap:**
-@.planning/ROADMAP.md
-
-</planning_context>
-
-<downstream_consumer>
-Output consumed by /qualia:execute-phase
-Plans must be executable prompts.
-</downstream_consumer>
-""",
-  subagent_type="qualia-planner",
-  model="{planner_model}",
-  description="Plan gap fixes for Phase {phase}"
-)
-```
-
-On return:
-- **PLANNING COMPLETE:** Proceed to `verify_gap_plans`
-- **PLANNING INCONCLUSIVE:** Report and offer manual intervention
-</step>
-
-<step name="verify_gap_plans">
-**Verify fix plans with checker:**
-
-Display:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► VERIFYING FIX PLANS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning plan checker...
-```
-
-Initialize: `iteration_count = 1`
-
-Spawn qualia-plan-checker:
-
-```
-Task(
-  prompt="""
-<verification_context>
-
-**Phase:** {phase_number}
-**Phase Goal:** Close diagnosed gaps from UAT
-
-**Plans to verify:**
-@.planning/phases/{phase_dir}/*-PLAN.md
-
-</verification_context>
-
-<expected_output>
-Return one of:
-- ## VERIFICATION PASSED — all checks pass
-- ## ISSUES FOUND — structured issue list
-</expected_output>
-""",
-  subagent_type="qualia-plan-checker",
-  model="{checker_model}",
-  description="Verify Phase {phase} fix plans"
-)
-```
-
-On return:
-- **VERIFICATION PASSED:** Proceed to `present_ready`
-- **ISSUES FOUND:** Proceed to `revision_loop`
-</step>
-
-<step name="revision_loop">
-**Iterate planner ↔ checker until plans pass (max 3):**
-
-**If iteration_count < 3:**
-
-Display: `Sending back to planner for revision... (iteration {N}/3)`
-
-Spawn qualia-planner with revision context:
-
-```
-Task(
-  prompt="""
-<revision_context>
-
-**Phase:** {phase_number}
-**Mode:** revision
-
-**Existing plans:**
-@.planning/phases/{phase_dir}/*-PLAN.md
-
-**Checker issues:**
-{structured_issues_from_checker}
-
-</revision_context>
-
-<instructions>
-Read existing PLAN.md files. Make targeted updates to address checker issues.
-Do NOT replan from scratch unless issues are fundamental.
-</instructions>
-""",
-  subagent_type="qualia-planner",
-  model="{planner_model}",
-  description="Revise Phase {phase} plans"
-)
-```
-
-After planner returns → spawn checker again (verify_gap_plans logic)
-Increment iteration_count
-
-**If iteration_count >= 3:**
-
-Display: `Max iterations reached. {N} issues remain.`
-
-Offer options:
-1. Force proceed (execute despite issues)
-2. Provide guidance (user gives direction, retry)
-3. Abandon (exit, user runs /qualia:plan-phase manually)
-
-Wait for user response.
-</step>
-
-<step name="present_ready">
-**Present completion and next steps:**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► FIXES READY ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Phase {X}: {Name}** — {N} gap(s) diagnosed, {M} fix plan(s) created
-
-| Gap | Root Cause | Fix Plan |
-|-----|------------|----------|
-| {truth 1} | {root_cause} | {phase}-04 |
-| {truth 2} | {root_cause} | {phase}-04 |
-
-Plans verified and ready for execution.
-
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Execute fixes** — run fix plans
-
-`/clear` then `/qualia:execute-phase {phase} --gaps-only`
-
-───────────────────────────────────────────────────────────────
-```
-</step>
-
-</process>
-
-<update_rules>
-**Batched writes for efficiency:**
-
-Keep results in memory. Write to file only when:
-1. **Issue found** — Preserve the problem immediately
-2. **Session complete** — Final write before commit
-3. **Checkpoint** — Every 5 passed tests (safety net)
-
-| Section | Rule | When Written |
-|---------|------|--------------|
-| Frontmatter.status | OVERWRITE | Start, complete |
-| Frontmatter.updated | OVERWRITE | On any file write |
-| Current Test | OVERWRITE | On any file write |
-| Tests.{N}.result | OVERWRITE | On any file write |
-| Summary | OVERWRITE | On any file write |
-| Gaps | APPEND | When issue found |
-
-On context reset: File shows last checkpoint. Resume from there.
-</update_rules>
-
-<severity_inference>
-**Infer severity from user's natural language:**
-
-| User says | Infer |
-|-----------|-------|
-| "crashes", "error", "exception", "fails completely" | blocker |
-| "doesn't work", "nothing happens", "wrong behavior" | major |
-| "works but...", "slow", "weird", "minor issue" | minor |
-| "color", "spacing", "alignment", "looks off" | cosmetic |
-
-Default to **major** if unclear. User can correct if needed.
-
-**Never ask "how severe is this?"** - just infer and move on.
-</severity_inference>
-
-<success_criteria>
-- [ ] UAT file created with all tests from SUMMARY.md
-- [ ] Tests presented one at a time with expected behavior
-- [ ] User responses processed as pass/issue/skip
-- [ ] Severity inferred from description (never asked)
-- [ ] Batched writes: on issue, every 5 passes, or completion
-- [ ] Committed on completion
-- [ ] If issues: parallel debug agents diagnose root causes
-- [ ] If issues: qualia-planner creates fix plans (gap_closure mode)
-- [ ] If issues: qualia-plan-checker verifies fix plans
-- [ ] If issues: revision loop until plans pass (max 3 iterations)
-- [ ] Ready for `/qualia:execute-phase --gaps-only` when complete
-</success_criteria>

package/framework/rules/context7.md

@@ -1,14 +0,0 @@
----
-alwaysApply: true
----
-
-Use Context7 MCP to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.
-
-Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.
-
-## Steps
-
-1. Always start with `resolve-library-id` using the library name and the user's question, unless the user provides an exact library ID in `/org/project` format
-2. Pick the best match (ID format: `/org/project`) by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try alternate names or queries (e.g., "next.js" not "nextjs", or rephrase the question). Use version-specific IDs when the user mentions a version
-3. `query-docs` with the selected library ID and the user's full question (not single words)
-4. Answer using the fetched docs

package/framework/rules/frontend.md

@@ -1,33 +0,0 @@
----
-globs: ["*.tsx", "*.jsx", "*.css", "*.scss", "tailwind.config.*"]
----
-
-# Frontend Aesthetics
-
-- Distinctive fonts (not Inter/Arial)
-- Cohesive color palette with sharp accents
-- CSS transitions, staggered animations
-- Layered backgrounds, subtle gradients
-- Avoid: card grids, generic heroes, blue-purple gradients
-- Full-width layouts — no hardcoded 1200px/1280px caps. Use fluid widths that fill the viewport with sensible padding.
-
-Note: Qualia agents MUST follow these rules when building any frontend component. These are Fawzi's brand standards, not suggestions.
-
-## Impeccable Design Skills (global)
-Use these `/commands` for design refinement on any frontend work:
-- `/polish` — Final detail pass before shipping (spacing, alignment, consistency)
-- `/bolder` — Amplify safe/boring designs to be more striking
-- `/design-quieter` — Tone down overly aggressive designs
-- `/animate` — Add purposeful micro-interactions and motion
-- `/colorize` — Inject strategic color into monochrome UIs
-- `/clarify` — Fix unclear UX copy, labels, error messages
-- `/critique` — Design director-level review (run before shipping)
-- `/distill` — Strip unnecessary complexity
-- `/delight` — Add memorable touches and personality
-- `/harden` — Edge cases, overflow, i18n robustness
-- `/onboard` — First-time user experience flows
-- `/normalize` — Align with project design system
-- `/responsive` — Cross-device responsive adaptation
-
-### Recommended workflow
-1. Build feature → 2. `/critique` → 3. `/polish` → 4. `/harden` → ship

package/framework/rules/speed.md

@@ -1,23 +0,0 @@
----
-alwaysApply: true
----
-
-# Speed Rules (MANDATORY)
-
-**NEVER use Task(Explore) or Task(general-purpose) for simple file lookups or code searches.** Use direct tools instead:
-- **Glob** for finding files by name/pattern
-- **Grep** for searching code content
-- **Read** for reading specific files
-- Only use Task(Explore) when you genuinely need 5+ rounds of deep codebase archaeology
-
-**NEVER spawn subagents when direct tools work.** Subagents are slow — a direct Glob or Grep returns in seconds.
-
-**Bias toward action, not exploration.** If Fawzi asks you to fix something and you know the project structure, just do it.
-
-**Use shortcuts:**
-- `/ship` — Full deploy pipeline (quality gates → commit → deploy → verify)
-- `/status` — Quick project health check
-- `/qualia-review` — Deep security + quality audit
-- `/memory` — View/manage persistent rules
-- `/learn` — Save a lesson from a mistake
-- `/qualia-pause-work` — Save context before /clear