qualia-framework 2.6.0 → 3.1.0

package/framework/qualia-framework/workflows/update.md

@@ -1,197 +0,0 @@
-<purpose>
-Check for Qualia updates via npm, display changelog for versions between installed and latest, obtain user confirmation, and execute clean installation with cache clearing.
-</purpose>
-
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-
-<process>
-
-<step name="get_installed_version">
-Detect whether Qualia is installed locally or globally by checking both locations:
-
-```bash
-# Check local first (takes priority)
-if [ -f "./.claude/qualia-framework/VERSION" ]; then
-  cat "./.claude/qualia-framework/VERSION"
-  echo "LOCAL"
-elif [ -f /home/qualia/.claude/qualia-framework/VERSION ]; then
-  cat /home/qualia/.claude/qualia-framework/VERSION
-  echo "GLOBAL"
-else
-  echo "UNKNOWN"
-fi
-```
-
-Parse output:
-- If last line is "LOCAL": installed version is first line, use `--local` flag for update
-- If last line is "GLOBAL": installed version is first line, use `--global` flag for update
-- If "UNKNOWN": proceed to install step (treat as version 0.0.0)
-
-**If VERSION file missing:**
-```
-## Qualia Update
-
-**Installed version:** Unknown
-
-Your installation doesn't include version tracking.
-
-Running fresh install...
-```
-
-Proceed to install step (treat as version 0.0.0 for comparison).
-</step>
-
-<step name="check_latest_version">
-Check npm for latest version:
-
-```bash
-npm view qualia-framework-cc version 2>/dev/null
-```
-
-**If npm check fails:**
-```
-Couldn't check for updates (offline or npm unavailable).
-
-To update manually: `npx qualia-framework-cc --global`
-```
-
-Exit.
-</step>
-
-<step name="compare_versions">
-Compare installed vs latest:
-
-**If installed == latest:**
-```
-## Qualia Update
-
-**Installed:** X.Y.Z
-**Latest:** X.Y.Z
-
-You're already on the latest version.
-```
-
-Exit.
-
-**If installed > latest:**
-```
-## Qualia Update
-
-**Installed:** X.Y.Z
-**Latest:** A.B.C
-
-You're ahead of the latest release (development version?).
-```
-
-Exit.
-</step>
-
-<step name="show_changes_and_confirm">
-**If update available**, fetch and show what's new BEFORE updating:
-
-1. Fetch changelog from GitHub raw URL
-2. Extract entries between installed and latest versions
-3. Display preview and ask for confirmation:
-
-```
-## Qualia Update Available
-
-**Installed:** 1.5.10
-**Latest:** 1.5.15
-
-### What's New
-────────────────────────────────────────────────────────────
-
-## [1.5.15] - 2026-01-20
-
-### Added
-- Feature X
-
-## [1.5.14] - 2026-01-18
-
-### Fixed
-- Bug fix Y
-
-────────────────────────────────────────────────────────────
-
-⚠️  **Note:** The installer performs a clean install of Qualia folders:
-- `skills/qualia/` will be wiped and replaced
-- `qualia-framework/` will be wiped and replaced
-- `agents/qualia-*` files will be replaced
-
-(Paths are relative to your install location: `/home/qualia/.claude/` for global, `./.claude/` for local)
-
-Your custom files in other locations are preserved:
-- Custom commands not in `skills/qualia/` ✓
-- Custom agents not prefixed with `qualia-` ✓
-- Custom hooks ✓
-- Your CLAUDE.md files ✓
-
-If you've modified any Qualia files directly, back them up first.
-```
-
-Use AskUserQuestion:
-- Question: "Proceed with update?"
-- Options:
-  - "Yes, update now"
-  - "No, cancel"
-
-**If user cancels:** Exit.
-</step>
-
-<step name="run_update">
-Run the update using the install type detected in step 1:
-
-**If LOCAL install:**
-```bash
-npx qualia-framework-cc --local
-```
-
-**If GLOBAL install (or unknown):**
-```bash
-npx qualia-framework-cc --global
-```
-
-Capture output. If install fails, show error and exit.
-
-Clear the update cache so statusline indicator disappears:
-
-**If LOCAL install:**
-```bash
-rm -f ./.claude/cache/qualia-update-check.json
-```
-
-**If GLOBAL install:**
-```bash
-rm -f /home/qualia/.claude/cache/qualia-update-check.json
-```
-</step>
-
-<step name="display_result">
-Format completion message (changelog was already shown in confirmation step):
-
-```
-╔═══════════════════════════════════════════════════════════╗
-║  Qualia Updated: v1.5.10 → v1.5.15                           ║
-╚═══════════════════════════════════════════════════════════╝
-
-⚠️  Restart Claude Code to pick up the new commands.
-
-[View full changelog](https://github.com/glittercowboy/qualia-framework/blob/main/CHANGELOG.md)
-```
-</step>
-
-</process>
-
-<success_criteria>
-- [ ] Installed version read correctly
-- [ ] Latest version checked via npm
-- [ ] Update skipped if already current
-- [ ] Changelog fetched and displayed BEFORE update
-- [ ] Clean install warning shown
-- [ ] User confirmation obtained
-- [ ] Update executed successfully
-- [ ] Restart reminder shown
-</success_criteria>

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

@@ -1,195 +0,0 @@
-<purpose>
-Verify phase goal achievement through goal-backward analysis. Check that the codebase delivers what the phase promised, not just that tasks completed.
-
-Executed by a verification subagent spawned from execute-phase.md.
-</purpose>
-
-<core_principle>
-**Task completion ≠ Goal achievement**
-
-A task "create chat component" can be marked complete when the component is a placeholder. The task was done — but the goal "working chat interface" was not achieved.
-
-Goal-backward verification:
-1. What must be TRUE for the goal to be achieved?
-2. What must EXIST for those truths to hold?
-3. What must be WIRED for those artifacts to function?
-
-Then verify each level against the actual codebase.
-</core_principle>
-
-<required_reading>
-@/home/qualia/.claude/qualia-framework/references/verification-patterns.md
-@/home/qualia/.claude/qualia-framework/templates/verification-report.md
-</required_reading>
-
-<process>
-
-<step name="load_context" priority="first">
-Load phase operation context:
-
-```bash
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init phase-op "${PHASE_ARG}")
-```
-
-Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `has_plans`, `plan_count`.
-
-Then load phase details and list plans/summaries:
-```bash
-node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js roadmap get-phase "${phase_number}"
-grep -E "^| ${phase_number}" .planning/REQUIREMENTS.md 2>/dev/null
-ls "$phase_dir"/*-SUMMARY.md "$phase_dir"/*-PLAN.md 2>/dev/null
-```
-
-Extract **phase goal** from ROADMAP.md (the outcome to verify, not tasks) and **requirements** from REQUIREMENTS.md if it exists.
-</step>
-
-<step name="establish_must_haves">
-**Option A: Must-haves in PLAN frontmatter**
-
-```bash
-grep -l "must_haves:" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
-```
-
-If found, extract truths, artifacts (with paths), and key_links (from/to/via).
-
-**Option B: Derive from phase goal**
-
-If no must_haves in frontmatter:
-1. State the goal from ROADMAP.md
-2. Derive **truths** (3-7 observable behaviors, each testable)
-3. Derive **artifacts** (concrete file paths for each truth)
-4. Derive **key links** (critical wiring where stubs hide)
-5. Document derived must-haves before proceeding
-</step>
-
-<step name="verify_truths">
-For each observable truth, determine if the codebase enables it.
-
-**Status:** ✓ VERIFIED (all supporting artifacts pass) | ✗ FAILED (artifact missing/stub/unwired) | ? UNCERTAIN (needs human)
-
-For each truth: identify supporting artifacts → check artifact status → check wiring → determine truth status.
-
-**Example:** Truth "User can see existing messages" depends on Chat.tsx (renders), /api/chat GET (provides), Message model (schema). If Chat.tsx is a stub or API returns hardcoded [] → FAILED. If all exist, are substantive, and connected → VERIFIED.
-</step>
-
-<step name="verify_artifacts">
-For each required artifact, verify three levels:
-
-**Level 1 — Existence:** File/directory exists. If MISSING → record and continue.
-
-**Level 2 — Substantive:** Real implementation, not a stub.
-- Line minimums: Component 15+, API route 10+, Hook/util 10+, Schema 5+
-- Stub detection: `TODO|FIXME|placeholder|not implemented|coming soon`, empty returns (`return null|return {}|return []`), placeholder content
-- Export check: `export (default )?(function|const|class)` exists
-- SUBSTANTIVE = adequate length + no stubs + has exports. STUB = too short OR stub patterns OR no exports. PARTIAL = mixed.
-
-**Level 3 — Wired:** Connected to the system.
-- Import: `grep -r "import.*$artifact_name" src/ --include="*.ts" --include="*.tsx"` → IMPORTED
-- Usage: same grep excluding import lines → USED
-- WIRED = imported AND used. ORPHANED = exists but not imported/used. PARTIAL = imported but unused.
-
-| Exists | Substantive | Wired | Status |
-|--------|-------------|-------|--------|
-| ✓ | ✓ | ✓ | ✓ VERIFIED |
-| ✓ | ✓ | ✗ | ⚠️ ORPHANED |
-| ✓ | ✗ | - | ✗ STUB |
-| ✗ | - | - | ✗ MISSING |
-</step>
-
-<step name="verify_wiring">
-Key links are critical connections — if broken, goal fails even with all artifacts present.
-
-| Pattern | Check | Status |
-|---------|-------|--------|
-| Component → API | fetch/axios call to API path, response used (await/.then/setState) | WIRED / PARTIAL (call but unused response) / NOT_WIRED |
-| API → Database | Prisma/DB query on model, result returned via res.json() | WIRED / PARTIAL (query but not returned) / NOT_WIRED |
-| Form → Handler | onSubmit with real implementation (fetch/axios/mutate/dispatch), not console.log/empty | WIRED / STUB (log-only/empty) / NOT_WIRED |
-| State → Render | useState variable appears in JSX (`{stateVar}` or `{stateVar.property}`) | WIRED / NOT_WIRED |
-
-Record status and evidence for each key link.
-</step>
-
-<step name="verify_requirements">
-If REQUIREMENTS.md exists:
-```bash
-grep -E "Phase ${PHASE_NUM}" .planning/REQUIREMENTS.md 2>/dev/null
-```
-
-For each requirement: parse description → identify supporting truths/artifacts → status: ✓ SATISFIED / ✗ BLOCKED / ? NEEDS HUMAN.
-</step>
-
-<step name="scan_antipatterns">
-Extract files modified in this phase from SUMMARY.md, scan each:
-
-| Pattern | Search | Severity |
-|---------|--------|----------|
-| TODO/FIXME/XXX/HACK | `grep -n -E "TODO\|FIXME\|XXX\|HACK"` | ⚠️ Warning |
-| Placeholder content | `grep -n -iE "placeholder\|coming soon\|will be here"` | 🛑 Blocker |
-| Empty returns | `grep -n -E "return null\|return \{\}\|return \[\]\|=> \{\}"` | ⚠️ Warning |
-| Log-only functions | Functions containing only console.log | ⚠️ Warning |
-
-Categorize: 🛑 Blocker (prevents goal) | ⚠️ Warning (incomplete) | ℹ️ Info (notable).
-</step>
-
-<step name="identify_human_verification">
-**Always needs human:** Visual appearance, user flow completion, real-time behavior (WebSocket/SSE), external service integration, performance feel, error message clarity.
-
-**Needs human if uncertain:** Complex wiring grep can't trace, dynamic state-dependent behavior, edge cases.
-
-Format each as: Test Name → What to do → Expected result → Why can't verify programmatically.
-</step>
-
-<step name="determine_status">
-**passed:** All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns.
-
-**gaps_found:** Any truth FAILED, artifact MISSING/STUB, key link NOT_WIRED, or blocker found.
-
-**human_needed:** All automated checks pass but human verification items remain.
-
-**Score:** `verified_truths / total_truths`
-</step>
-
-<step name="generate_fix_plans">
-If gaps_found:
-
-1. **Cluster related gaps:** API stub + component unwired → "Wire frontend to backend". Multiple missing → "Complete core implementation". Wiring only → "Connect existing components".
-
-2. **Generate plan per cluster:** Objective, 2-3 tasks (files/action/verify each), re-verify step. Keep focused: single concern per plan.
-
-3. **Order by dependency:** Fix missing → fix stubs → fix wiring → verify.
-</step>
-
-<step name="create_report">
-```bash
-REPORT_PATH="$PHASE_DIR/${PHASE_NUM}-VERIFICATION.md"
-```
-
-Fill template sections: frontmatter (phase/timestamp/status/score), goal achievement, artifact table, wiring table, requirements coverage, anti-patterns, human verification, gaps summary, fix plans (if gaps_found), metadata.
-
-See /home/qualia/.claude/qualia-framework/templates/verification-report.md for complete template.
-</step>
-
-<step name="return_to_orchestrator">
-Return status (`passed` | `gaps_found` | `human_needed`), score (N/M must-haves), report path.
-
-If gaps_found: list gaps + recommended fix plan names.
-If human_needed: list items requiring human testing.
-
-Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execute fixes, re-verify | `human_needed` → present to user.
-</step>
-
-</process>
-
-<success_criteria>
-- [ ] Must-haves established (from frontmatter or derived)
-- [ ] All truths verified with status and evidence
-- [ ] All artifacts checked at all three levels
-- [ ] All key links verified
-- [ ] Requirements coverage assessed (if applicable)
-- [ ] Anti-patterns scanned and categorized
-- [ ] Human verification items identified
-- [ ] Overall status determined
-- [ ] Fix plans generated (if gaps_found)
-- [ ] VERIFICATION.md created with complete report
-- [ ] Results returned to orchestrator
-</success_criteria>