qualia-framework 2.6.0 → 3.2.0

package/framework/qualia-framework/templates/verification-report.md

@@ -1,322 +0,0 @@
-# Verification Report Template
-
-Template for `.planning/phases/XX-name/{phase}-VERIFICATION.md` — phase goal verification results.
-
----
-
-## File Template
-
-```markdown
----
-phase: XX-name
-verified: YYYY-MM-DDTHH:MM:SSZ
-status: passed | gaps_found | human_needed
-score: N/M must-haves verified
----
-
-# Phase {X}: {Name} Verification Report
-
-**Phase Goal:** {goal from ROADMAP.md}
-**Verified:** {timestamp}
-**Status:** {passed | gaps_found | human_needed}
-
-## Goal Achievement
-
-### Observable Truths
-
-| # | Truth | Status | Evidence |
-|---|-------|--------|----------|
-| 1 | {truth from must_haves} | ✓ VERIFIED | {what confirmed it} |
-| 2 | {truth from must_haves} | ✗ FAILED | {what's wrong} |
-| 3 | {truth from must_haves} | ? UNCERTAIN | {why can't verify} |
-
-**Score:** {N}/{M} truths verified
-
-### Required Artifacts
-
-| Artifact | Expected | Status | Details |
-|----------|----------|--------|---------|
-| `src/components/Chat.tsx` | Message list component | ✓ EXISTS + SUBSTANTIVE | Exports ChatList, renders Message[], no stubs |
-| `src/app/api/chat/route.ts` | Message CRUD | ✗ STUB | File exists but POST returns placeholder |
-| `prisma/schema.prisma` | Message model | ✓ EXISTS + SUBSTANTIVE | Model defined with all fields |
-
-**Artifacts:** {N}/{M} verified
-
-### Key Link Verification
-
-| From | To | Via | Status | Details |
-|------|----|----|--------|---------|
-| Chat.tsx | /api/chat | fetch in useEffect | ✓ WIRED | Line 23: `fetch('/api/chat')` with response handling |
-| ChatInput | /api/chat POST | onSubmit handler | ✗ NOT WIRED | onSubmit only calls console.log |
-| /api/chat POST | database | prisma.message.create | ✗ NOT WIRED | Returns hardcoded response, no DB call |
-
-**Wiring:** {N}/{M} connections verified
-
-## Requirements Coverage
-
-| Requirement | Status | Blocking Issue |
-|-------------|--------|----------------|
-| {REQ-01}: {description} | ✓ SATISFIED | - |
-| {REQ-02}: {description} | ✗ BLOCKED | API route is stub |
-| {REQ-03}: {description} | ? NEEDS HUMAN | Can't verify WebSocket programmatically |
-
-**Coverage:** {N}/{M} requirements satisfied
-
-## Anti-Patterns Found
-
-| File | Line | Pattern | Severity | Impact |
-|------|------|---------|----------|--------|
-| src/app/api/chat/route.ts | 12 | `// TODO: implement` | ⚠️ Warning | Indicates incomplete |
-| src/components/Chat.tsx | 45 | `return <div>Placeholder</div>` | 🛑 Blocker | Renders no content |
-| src/hooks/useChat.ts | - | File missing | 🛑 Blocker | Expected hook doesn't exist |
-
-**Anti-patterns:** {N} found ({blockers} blockers, {warnings} warnings)
-
-## Human Verification Required
-
-{If no human verification needed:}
-None — all verifiable items checked programmatically.
-
-{If human verification needed:}
-
-### 1. {Test Name}
-**Test:** {What to do}
-**Expected:** {What should happen}
-**Why human:** {Why can't verify programmatically}
-
-### 2. {Test Name}
-**Test:** {What to do}
-**Expected:** {What should happen}
-**Why human:** {Why can't verify programmatically}
-
-## Gaps Summary
-
-{If no gaps:}
-**No gaps found.** Phase goal achieved. Ready to proceed.
-
-{If gaps found:}
-
-### Critical Gaps (Block Progress)
-
-1. **{Gap name}**
-   - Missing: {what's missing}
-   - Impact: {why this blocks the goal}
-   - Fix: {what needs to happen}
-
-2. **{Gap name}**
-   - Missing: {what's missing}
-   - Impact: {why this blocks the goal}
-   - Fix: {what needs to happen}
-
-### Non-Critical Gaps (Can Defer)
-
-1. **{Gap name}**
-   - Issue: {what's wrong}
-   - Impact: {limited impact because...}
-   - Recommendation: {fix now or defer}
-
-## Recommended Fix Plans
-
-{If gaps found, generate fix plan recommendations:}
-
-### {phase}-{next}-PLAN.md: {Fix Name}
-
-**Objective:** {What this fixes}
-
-**Tasks:**
-1. {Task to fix gap 1}
-2. {Task to fix gap 2}
-3. {Verification task}
-
-**Estimated scope:** {Small / Medium}
-
----
-
-### {phase}-{next+1}-PLAN.md: {Fix Name}
-
-**Objective:** {What this fixes}
-
-**Tasks:**
-1. {Task}
-2. {Task}
-
-**Estimated scope:** {Small / Medium}
-
----
-
-## Verification Metadata
-
-**Verification approach:** Goal-backward (derived from phase goal)
-**Must-haves source:** {PLAN.md frontmatter | derived from ROADMAP.md goal}
-**Automated checks:** {N} passed, {M} failed
-**Human checks required:** {N}
-**Total verification time:** {duration}
-
----
-*Verified: {timestamp}*
-*Verifier: Claude (subagent)*
-```
-
----
-
-## Guidelines
-
-**Status values:**
-- `passed` — All must-haves verified, no blockers
-- `gaps_found` — One or more critical gaps found
-- `human_needed` — Automated checks pass but human verification required
-
-**Evidence types:**
-- For EXISTS: "File at path, exports X"
-- For SUBSTANTIVE: "N lines, has patterns X, Y, Z"
-- For WIRED: "Line N: code that connects A to B"
-- For FAILED: "Missing because X" or "Stub because Y"
-
-**Severity levels:**
-- 🛑 Blocker: Prevents goal achievement, must fix
-- ⚠️ Warning: Indicates incomplete but doesn't block
-- ℹ️ Info: Notable but not problematic
-
-**Fix plan generation:**
-- Only generate if gaps_found
-- Group related fixes into single plans
-- Keep to 2-3 tasks per plan
-- Include verification task in each plan
-
----
-
-## Example
-
-```markdown
----
-phase: 03-chat
-verified: 2025-01-15T14:30:00Z
-status: gaps_found
-score: 2/5 must-haves verified
----
-
-# Phase 3: Chat Interface Verification Report
-
-**Phase Goal:** Working chat interface where users can send and receive messages
-**Verified:** 2025-01-15T14:30:00Z
-**Status:** gaps_found
-
-## Goal Achievement
-
-### Observable Truths
-
-| # | Truth | Status | Evidence |
-|---|-------|--------|----------|
-| 1 | User can see existing messages | ✗ FAILED | Component renders placeholder, not message data |
-| 2 | User can type a message | ✓ VERIFIED | Input field exists with onChange handler |
-| 3 | User can send a message | ✗ FAILED | onSubmit handler is console.log only |
-| 4 | Sent message appears in list | ✗ FAILED | No state update after send |
-| 5 | Messages persist across refresh | ? UNCERTAIN | Can't verify - send doesn't work |
-
-**Score:** 1/5 truths verified
-
-### Required Artifacts
-
-| Artifact | Expected | Status | Details |
-|----------|----------|--------|---------|
-| `src/components/Chat.tsx` | Message list component | ✗ STUB | Returns `<div>Chat will be here</div>` |
-| `src/components/ChatInput.tsx` | Message input | ✓ EXISTS + SUBSTANTIVE | Form with input, submit button, handlers |
-| `src/app/api/chat/route.ts` | Message CRUD | ✗ STUB | GET returns [], POST returns { ok: true } |
-| `prisma/schema.prisma` | Message model | ✓ EXISTS + SUBSTANTIVE | Message model with id, content, userId, createdAt |
-
-**Artifacts:** 2/4 verified
-
-### Key Link Verification
-
-| From | To | Via | Status | Details |
-|------|----|----|--------|---------|
-| Chat.tsx | /api/chat GET | fetch | ✗ NOT WIRED | No fetch call in component |
-| ChatInput | /api/chat POST | onSubmit | ✗ NOT WIRED | Handler only logs, doesn't fetch |
-| /api/chat GET | database | prisma.message.findMany | ✗ NOT WIRED | Returns hardcoded [] |
-| /api/chat POST | database | prisma.message.create | ✗ NOT WIRED | Returns { ok: true }, no DB call |
-
-**Wiring:** 0/4 connections verified
-
-## Requirements Coverage
-
-| Requirement | Status | Blocking Issue |
-|-------------|--------|----------------|
-| CHAT-01: User can send message | ✗ BLOCKED | API POST is stub |
-| CHAT-02: User can view messages | ✗ BLOCKED | Component is placeholder |
-| CHAT-03: Messages persist | ✗ BLOCKED | No database integration |
-
-**Coverage:** 0/3 requirements satisfied
-
-## Anti-Patterns Found
-
-| File | Line | Pattern | Severity | Impact |
-|------|------|---------|----------|--------|
-| src/components/Chat.tsx | 8 | `<div>Chat will be here</div>` | 🛑 Blocker | No actual content |
-| src/app/api/chat/route.ts | 5 | `return Response.json([])` | 🛑 Blocker | Hardcoded empty |
-| src/app/api/chat/route.ts | 12 | `// TODO: save to database` | ⚠️ Warning | Incomplete |
-
-**Anti-patterns:** 3 found (2 blockers, 1 warning)
-
-## Human Verification Required
-
-None needed until automated gaps are fixed.
-
-## Gaps Summary
-
-### Critical Gaps (Block Progress)
-
-1. **Chat component is placeholder**
-   - Missing: Actual message list rendering
-   - Impact: Users see "Chat will be here" instead of messages
-   - Fix: Implement Chat.tsx to fetch and render messages
-
-2. **API routes are stubs**
-   - Missing: Database integration in GET and POST
-   - Impact: No data persistence, no real functionality
-   - Fix: Wire prisma calls in route handlers
-
-3. **No wiring between frontend and backend**
-   - Missing: fetch calls in components
-   - Impact: Even if API worked, UI wouldn't call it
-   - Fix: Add useEffect fetch in Chat, onSubmit fetch in ChatInput
-
-## Recommended Fix Plans
-
-### 03-04-PLAN.md: Implement Chat API
-
-**Objective:** Wire API routes to database
-
-**Tasks:**
-1. Implement GET /api/chat with prisma.message.findMany
-2. Implement POST /api/chat with prisma.message.create
-3. Verify: API returns real data, POST creates records
-
-**Estimated scope:** Small
-
----
-
-### 03-05-PLAN.md: Implement Chat UI
-
-**Objective:** Wire Chat component to API
-
-**Tasks:**
-1. Implement Chat.tsx with useEffect fetch and message rendering
-2. Wire ChatInput onSubmit to POST /api/chat
-3. Verify: Messages display, new messages appear after send
-
-**Estimated scope:** Small
-
----
-
-## Verification Metadata
-
-**Verification approach:** Goal-backward (derived from phase goal)
-**Must-haves source:** 03-01-PLAN.md frontmatter
-**Automated checks:** 2 passed, 8 failed
-**Human checks required:** 0 (blocked by automated failures)
-**Total verification time:** 2 min
-
----
-*Verified: 2025-01-15T14:30:00Z*
-*Verifier: Claude (subagent)*
-```

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

@@ -1,179 +0,0 @@
-<purpose>
-Add a new integer phase to the end of the current milestone in the roadmap. Automatically calculates next phase number, creates phase directory, and updates roadmap structure.
-</purpose>
-
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-
-<process>
-
-<step name="parse_arguments">
-Parse the command arguments:
-- All arguments become the phase description
-- Example: `/qualia:add-phase Add authentication` → description = "Add authentication"
-- Example: `/qualia:add-phase Fix critical performance issues` → description = "Fix critical performance issues"
-
-If no arguments provided:
-
-```
-ERROR: Phase description required
-Usage: /qualia:add-phase <description>
-Example: /qualia:add-phase Add authentication system
-```
-
-Exit.
-</step>
-
-<step name="init_context">
-Load phase operation context:
-
-```bash
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init phase-op "0")
-```
-
-Check `roadmap_exists` from init JSON. If false:
-```
-ERROR: No roadmap found (.planning/ROADMAP.md)
-Run /qualia:new-project to initialize.
-```
-Exit.
-
-Read roadmap content for parsing.
-</step>
-
-<step name="find_current_milestone">
-Parse the roadmap to find the current milestone section:
-
-1. Locate the "## Current Milestone:" heading
-2. Extract milestone name and version
-3. Identify all phases under this milestone (before next "---" separator or next milestone heading)
-4. Parse existing phase numbers (including decimals if present)
-
-Example structure:
-
-```
-## Current Milestone: v1.0 Foundation
-
-### Phase 4: Focused Command System
-### Phase 5: Path Routing & Validation
-### Phase 6: Documentation & Distribution
-```
-</step>
-
-<step name="calculate_next_phase">
-Find the highest integer phase number in the current milestone:
-
-1. Extract all phase numbers from phase headings (### Phase N:)
-2. Filter to integer phases only (ignore decimals like 4.1, 4.2)
-3. Find the maximum integer value
-4. Add 1 to get the next phase number
-
-Example: If phases are 4, 5, 5.1, 6 → next is 7
-
-Format as two-digit: `printf "%02d" $next_phase`
-</step>
-
-<step name="generate_slug">
-Convert the phase description to a kebab-case slug.
-
-Use `init phase-op` which provides `phase_slug` computed from phase name, or call:
-```bash
-slug=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js generate-slug "$description" --raw)
-```
-
-Phase directory name: `{two-digit-phase}-{slug}`
-Example: `07-add-authentication`
-</step>
-
-<step name="create_phase_directory">
-Create the phase directory structure:
-
-```bash
-phase_dir=".planning/phases/${phase_num}-${slug}"
-mkdir -p "$phase_dir"
-```
-
-Confirm: "Created directory: $phase_dir"
-</step>
-
-<step name="update_roadmap">
-Add the new phase entry to the roadmap:
-
-1. Find the insertion point (after last phase in current milestone, before "---" separator)
-2. Insert new phase heading:
-
-   ```
-   ### Phase {N}: {Description}
-
-   **Goal:** [To be planned]
-   **Depends on:** Phase {N-1}
-   **Plans:** 0 plans
-
-   Plans:
-   - [ ] TBD (run /qualia:plan-phase {N} to break down)
-
-   **Details:**
-   [To be added during planning]
-   ```
-
-3. Write updated roadmap back to file
-
-Preserve all other content exactly (formatting, spacing, other phases).
-</step>
-
-<step name="update_project_state">
-Update STATE.md to reflect the new phase:
-
-1. Read `.planning/STATE.md`
-2. Under "## Current Position" → "**Next Phase:**" add reference to new phase
-3. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
-   ```
-   - Phase {N} added: {description}
-   ```
-
-If "Roadmap Evolution" section doesn't exist, create it.
-</step>
-
-<step name="completion">
-Present completion summary:
-
-```
-Phase {N} added to current milestone:
-- Description: {description}
-- Directory: .planning/phases/{phase-num}-{slug}/
-- Status: Not planned yet
-
-Roadmap updated: .planning/ROADMAP.md
-Project state updated: .planning/STATE.md
-
----
-
-## ▶ Next Up
-
-**Phase {N}: {description}**
-
-`/qualia:plan-phase {N}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/qualia:add-phase <description>` — add another phase
-- Review roadmap
-
----
-```
-</step>
-
-</process>
-
-<success_criteria>
-- [ ] Phase directory created: `.planning/phases/{NN}-{slug}/`
-- [ ] Roadmap updated with new phase entry
-- [ ] STATE.md updated with roadmap evolution note
-- [ ] New phase appears at end of current milestone
-- [ ] Next phase number calculated correctly (ignoring decimals)
-- [ ] User informed of next steps
-</success_criteria>

package/framework/qualia-framework/workflows/add-todo.md

@@ -1,157 +0,0 @@
-<purpose>
-Capture an idea, task, or issue that surfaces during a Qualia session as a structured todo for later work. Enables "thought → capture → continue" flow without losing context.
-</purpose>
-
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-
-<process>
-
-<step name="init_context">
-Load todo context:
-
-```bash
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init todos)
-```
-
-Extract from init JSON: `commit_docs`, `date`, `timestamp`, `todo_count`, `todos`, `pending_dir`, `todos_dir_exists`.
-
-Ensure directories exist:
-```bash
-mkdir -p .planning/todos/pending .planning/todos/done
-```
-
-Note existing areas from the todos array for consistency in infer_area step.
-</step>
-
-<step name="extract_content">
-**With arguments:** Use as the title/focus.
-- `/qualia:add-todo Add auth token refresh` → title = "Add auth token refresh"
-
-**Without arguments:** Analyze recent conversation to extract:
-- The specific problem, idea, or task discussed
-- Relevant file paths mentioned
-- Technical details (error messages, line numbers, constraints)
-
-Formulate:
-- `title`: 3-10 word descriptive title (action verb preferred)
-- `problem`: What's wrong or why this is needed
-- `solution`: Approach hints or "TBD" if just an idea
-- `files`: Relevant paths with line numbers from conversation
-</step>
-
-<step name="infer_area">
-Infer area from file paths:
-
-| Path pattern | Area |
-|--------------|------|
-| `src/api/*`, `api/*` | `api` |
-| `src/components/*`, `src/ui/*` | `ui` |
-| `src/auth/*`, `auth/*` | `auth` |
-| `src/db/*`, `database/*` | `database` |
-| `tests/*`, `__tests__/*` | `testing` |
-| `docs/*` | `docs` |
-| `.planning/*` | `planning` |
-| `scripts/*`, `bin/*` | `tooling` |
-| No files or unclear | `general` |
-
-Use existing area from step 2 if similar match exists.
-</step>
-
-<step name="check_duplicates">
-```bash
-# Search for key words from title in existing todos
-grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null
-```
-
-If potential duplicate found:
-1. Read the existing todo
-2. Compare scope
-
-If overlapping, use AskUserQuestion:
-- header: "Duplicate?"
-- question: "Similar todo exists: [title]. What would you like to do?"
-- options:
-  - "Skip" — keep existing todo
-  - "Replace" — update existing with new context
-  - "Add anyway" — create as separate todo
-</step>
-
-<step name="create_file">
-Use values from init context: `timestamp` and `date` are already available.
-
-Generate slug for the title:
-```bash
-slug=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js generate-slug "$title" --raw)
-```
-
-Write to `.planning/todos/pending/${date}-${slug}.md`:
-
-```markdown
----
-created: [timestamp]
-title: [title]
-area: [area]
-files:
-  - [file:lines]
----
-
-## Problem
-
-[problem description - enough context for future Claude to understand weeks later]
-
-## Solution
-
-[approach hints or "TBD"]
-```
-</step>
-
-<step name="update_state">
-If `.planning/STATE.md` exists:
-
-1. Use `todo_count` from init context (or re-run `init todos` if count changed)
-2. Update "### Pending Todos" under "## Accumulated Context"
-</step>
-
-<step name="git_commit">
-Commit the todo and any updated state:
-
-```bash
-node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "docs: capture todo - [title]" --files .planning/todos/pending/[filename] .planning/STATE.md
-```
-
-Tool respects `commit_docs` config and gitignore automatically.
-
-Confirm: "Committed: docs: capture todo - [title]"
-</step>
-
-<step name="confirm">
-```
-Todo saved: .planning/todos/pending/[filename]
-
-  [title]
-  Area: [area]
-  Files: [count] referenced
-
----
-
-Would you like to:
-
-1. Continue with current work
-2. Add another todo
-3. View all todos (/qualia:check-todos)
-```
-</step>
-
-</process>
-
-<success_criteria>
-- [ ] Directory structure exists
-- [ ] Todo file created with valid frontmatter
-- [ ] Problem section has enough context for future Claude
-- [ ] No duplicates (checked and resolved)
-- [ ] Area consistent with existing todos
-- [ ] STATE.md updated if exists
-- [ ] Todo and state committed to git
-</success_criteria>