qualia-framework 2.6.0 → 3.2.0

package/framework/qualia-framework/templates/summary.md

@@ -1,246 +0,0 @@
-# Summary Template
-
-Template for `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md` - phase completion documentation.
-
----
-
-## File Template
-
-```markdown
----
-phase: XX-name
-plan: YY
-subsystem: [primary category: auth, payments, ui, api, database, infra, testing, etc.]
-tags: [searchable tech: jwt, stripe, react, postgres, prisma]
-
-# Dependency graph
-requires:
-  - phase: [prior phase this depends on]
-    provides: [what that phase built that this uses]
-provides:
-  - [bullet list of what this phase built/delivered]
-affects: [list of phase names or keywords that will need this context]
-
-# Tech tracking
-tech-stack:
-  added: [libraries/tools added in this phase]
-  patterns: [architectural/code patterns established]
-
-key-files:
-  created: [important files created]
-  modified: [important files modified]
-
-key-decisions:
-  - "Decision 1"
-  - "Decision 2"
-
-patterns-established:
-  - "Pattern 1: description"
-  - "Pattern 2: description"
-
-# Metrics
-duration: Xmin
-completed: YYYY-MM-DD
----
-
-# Phase [X]: [Name] Summary
-
-**[Substantive one-liner describing outcome - NOT "phase complete" or "implementation finished"]**
-
-## Performance
-
-- **Duration:** [time] (e.g., 23 min, 1h 15m)
-- **Started:** [ISO timestamp]
-- **Completed:** [ISO timestamp]
-- **Tasks:** [count completed]
-- **Files modified:** [count]
-
-## Accomplishments
-- [Most important outcome]
-- [Second key accomplishment]
-- [Third if applicable]
-
-## Task Commits
-
-Each task was committed atomically:
-
-1. **Task 1: [task name]** - `abc123f` (feat/fix/test/refactor)
-2. **Task 2: [task name]** - `def456g` (feat/fix/test/refactor)
-3. **Task 3: [task name]** - `hij789k` (feat/fix/test/refactor)
-
-**Plan metadata:** `lmn012o` (docs: complete plan)
-
-_Note: TDD tasks may have multiple commits (test → feat → refactor)_
-
-## Files Created/Modified
-- `path/to/file.ts` - What it does
-- `path/to/another.ts` - What it does
-
-## Decisions Made
-[Key decisions with brief rationale, or "None - followed plan as specified"]
-
-## Deviations from Plan
-
-[If no deviations: "None - plan executed exactly as written"]
-
-[If deviations occurred:]
-
-### Auto-fixed Issues
-
-**1. [Rule X - Category] Brief description**
-- **Found during:** Task [N] ([task name])
-- **Issue:** [What was wrong]
-- **Fix:** [What was done]
-- **Files modified:** [file paths]
-- **Verification:** [How it was verified]
-- **Committed in:** [hash] (part of task commit)
-
-[... repeat for each auto-fix ...]
-
----
-
-**Total deviations:** [N] auto-fixed ([breakdown by rule])
-**Impact on plan:** [Brief assessment - e.g., "All auto-fixes necessary for correctness/security. No scope creep."]
-
-## Issues Encountered
-[Problems and how they were resolved, or "None"]
-
-[Note: "Deviations from Plan" documents unplanned work that was handled automatically via deviation rules. "Issues Encountered" documents problems during planned work that required problem-solving.]
-
-## User Setup Required
-
-[If USER-SETUP.md was generated:]
-**External services require manual configuration.** See [{phase}-USER-SETUP.md](./{phase}-USER-SETUP.md) for:
-- Environment variables to add
-- Dashboard configuration steps
-- Verification commands
-
-[If no USER-SETUP.md:]
-None - no external service configuration required.
-
-## Next Phase Readiness
-[What's ready for next phase]
-[Any blockers or concerns]
-
----
-*Phase: XX-name*
-*Completed: [date]*
-```
-
-<frontmatter_guidance>
-**Purpose:** Enable automatic context assembly via dependency graph. Frontmatter makes summary metadata machine-readable so plan-phase can scan all summaries quickly and select relevant ones based on dependencies.
-
-**Fast scanning:** Frontmatter is first ~25 lines, cheap to scan across all summaries without reading full content.
-
-**Dependency graph:** `requires`/`provides`/`affects` create explicit links between phases, enabling transitive closure for context selection.
-
-**Subsystem:** Primary categorization (auth, payments, ui, api, database, infra, testing) for detecting related phases.
-
-**Tags:** Searchable technical keywords (libraries, frameworks, tools) for tech stack awareness.
-
-**Key-files:** Important files for @context references in PLAN.md.
-
-**Patterns:** Established conventions future phases should maintain.
-
-**Population:** Frontmatter is populated during summary creation in execute-plan.md. See `<step name="create_summary">` for field-by-field guidance.
-</frontmatter_guidance>
-
-<one_liner_rules>
-The one-liner MUST be substantive:
-
-**Good:**
-- "JWT auth with refresh rotation using jose library"
-- "Prisma schema with User, Session, and Product models"
-- "Dashboard with real-time metrics via Server-Sent Events"
-
-**Bad:**
-- "Phase complete"
-- "Authentication implemented"
-- "Foundation finished"
-- "All tasks done"
-
-The one-liner should tell someone what actually shipped.
-</one_liner_rules>
-
-<example>
-```markdown
-# Phase 1: Foundation Summary
-
-**JWT auth with refresh rotation using jose library, Prisma User model, and protected API middleware**
-
-## Performance
-
-- **Duration:** 28 min
-- **Started:** 2025-01-15T14:22:10Z
-- **Completed:** 2025-01-15T14:50:33Z
-- **Tasks:** 5
-- **Files modified:** 8
-
-## Accomplishments
-- User model with email/password auth
-- Login/logout endpoints with httpOnly JWT cookies
-- Protected route middleware checking token validity
-- Refresh token rotation on each request
-
-## Files Created/Modified
-- `prisma/schema.prisma` - User and Session models
-- `src/app/api/auth/login/route.ts` - Login endpoint
-- `src/app/api/auth/logout/route.ts` - Logout endpoint
-- `src/middleware.ts` - Protected route checks
-- `src/lib/auth.ts` - JWT helpers using jose
-
-## Decisions Made
-- Used jose instead of jsonwebtoken (ESM-native, Edge-compatible)
-- 15-min access tokens with 7-day refresh tokens
-- Storing refresh tokens in database for revocation capability
-
-## Deviations from Plan
-
-### Auto-fixed Issues
-
-**1. [Rule 2 - Missing Critical] Added password hashing with bcrypt**
-- **Found during:** Task 2 (Login endpoint implementation)
-- **Issue:** Plan didn't specify password hashing - storing plaintext would be critical security flaw
-- **Fix:** Added bcrypt hashing on registration, comparison on login with salt rounds 10
-- **Files modified:** src/app/api/auth/login/route.ts, src/lib/auth.ts
-- **Verification:** Password hash test passes, plaintext never stored
-- **Committed in:** abc123f (Task 2 commit)
-
-**2. [Rule 3 - Blocking] Installed missing jose dependency**
-- **Found during:** Task 4 (JWT token generation)
-- **Issue:** jose package not in package.json, import failing
-- **Fix:** Ran `npm install jose`
-- **Files modified:** package.json, package-lock.json
-- **Verification:** Import succeeds, build passes
-- **Committed in:** def456g (Task 4 commit)
-
----
-
-**Total deviations:** 2 auto-fixed (1 missing critical, 1 blocking)
-**Impact on plan:** Both auto-fixes essential for security and functionality. No scope creep.
-
-## Issues Encountered
-- jsonwebtoken CommonJS import failed in Edge runtime - switched to jose (planned library change, worked as expected)
-
-## Next Phase Readiness
-- Auth foundation complete, ready for feature development
-- User registration endpoint needed before public launch
-
----
-*Phase: 01-foundation*
-*Completed: 2025-01-15*
-```
-</example>
-
-<guidelines>
-**Frontmatter:** MANDATORY - complete all fields. Enables automatic context assembly for future planning.
-
-**One-liner:** Must be substantive. "JWT auth with refresh rotation using jose library" not "Authentication implemented".
-
-**Decisions section:**
-- Key decisions made during execution with rationale
-- Extracted to STATE.md accumulated context
-- Use "None - followed plan as specified" if no deviations
-
-**After creation:** STATE.md updated with position, decisions, issues.
-</guidelines>

package/framework/qualia-framework/templates/user-setup.md

@@ -1,311 +0,0 @@
-# User Setup Template
-
-Template for `.planning/phases/XX-name/{phase}-USER-SETUP.md` - human-required configuration that Claude cannot automate.
-
-**Purpose:** Document setup tasks that literally require human action - account creation, dashboard configuration, secret retrieval. Claude automates everything possible; this file captures only what remains.
-
----
-
-## File Template
-
-```markdown
-# Phase {X}: User Setup Required
-
-**Generated:** [YYYY-MM-DD]
-**Phase:** {phase-name}
-**Status:** Incomplete
-
-Complete these items for the integration to function. Claude automated everything possible; these items require human access to external dashboards/accounts.
-
-## Environment Variables
-
-| Status | Variable | Source | Add to |
-|--------|----------|--------|--------|
-| [ ] | `ENV_VAR_NAME` | [Service Dashboard → Path → To → Value] | `.env.local` |
-| [ ] | `ANOTHER_VAR` | [Service Dashboard → Path → To → Value] | `.env.local` |
-
-## Account Setup
-
-[Only if new account creation is required]
-
-- [ ] **Create [Service] account**
-  - URL: [signup URL]
-  - Skip if: Already have account
-
-## Dashboard Configuration
-
-[Only if dashboard configuration is required]
-
-- [ ] **[Configuration task]**
-  - Location: [Service Dashboard → Path → To → Setting]
-  - Set to: [Required value or configuration]
-  - Notes: [Any important details]
-
-## Verification
-
-After completing setup, verify with:
-
-```bash
-# [Verification commands]
-```
-
-Expected results:
-- [What success looks like]
-
----
-
-**Once all items complete:** Mark status as "Complete" at top of file.
-```
-
----
-
-## When to Generate
-
-Generate `{phase}-USER-SETUP.md` when plan frontmatter contains `user_setup` field.
-
-**Trigger:** `user_setup` exists in PLAN.md frontmatter and has items.
-
-**Location:** Same directory as PLAN.md and SUMMARY.md.
-
-**Timing:** Generated during execute-plan.md after tasks complete, before SUMMARY.md creation.
-
----
-
-## Frontmatter Schema
-
-In PLAN.md, `user_setup` declares human-required configuration:
-
-```yaml
-user_setup:
-  - service: stripe
-    why: "Payment processing requires API keys"
-    env_vars:
-      - name: STRIPE_SECRET_KEY
-        source: "Stripe Dashboard → Developers → API keys → Secret key"
-      - name: STRIPE_WEBHOOK_SECRET
-        source: "Stripe Dashboard → Developers → Webhooks → Signing secret"
-    dashboard_config:
-      - task: "Create webhook endpoint"
-        location: "Stripe Dashboard → Developers → Webhooks → Add endpoint"
-        details: "URL: https://[your-domain]/api/webhooks/stripe, Events: checkout.session.completed, customer.subscription.*"
-    local_dev:
-      - "Run: stripe listen --forward-to localhost:3000/api/webhooks/stripe"
-      - "Use the webhook secret from CLI output for local testing"
-```
-
----
-
-## The Automation-First Rule
-
-**USER-SETUP.md contains ONLY what Claude literally cannot do.**
-
-| Claude CAN Do (not in USER-SETUP) | Claude CANNOT Do (→ USER-SETUP) |
-|-----------------------------------|--------------------------------|
-| `npm install stripe` | Create Stripe account |
-| Write webhook handler code | Get API keys from dashboard |
-| Create `.env.local` file structure | Copy actual secret values |
-| Run `stripe listen` | Authenticate Stripe CLI (browser OAuth) |
-| Configure package.json | Access external service dashboards |
-| Write any code | Retrieve secrets from third-party systems |
-
-**The test:** "Does this require a human in a browser, accessing an account Claude doesn't have credentials for?"
-- Yes → USER-SETUP.md
-- No → Claude does it automatically
-
----
-
-## Service-Specific Examples
-
-<stripe_example>
-```markdown
-# Phase 10: User Setup Required
-
-**Generated:** 2025-01-14
-**Phase:** 10-monetization
-**Status:** Incomplete
-
-Complete these items for Stripe integration to function.
-
-## Environment Variables
-
-| Status | Variable | Source | Add to |
-|--------|----------|--------|--------|
-| [ ] | `STRIPE_SECRET_KEY` | Stripe Dashboard → Developers → API keys → Secret key | `.env.local` |
-| [ ] | `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Stripe Dashboard → Developers → API keys → Publishable key | `.env.local` |
-| [ ] | `STRIPE_WEBHOOK_SECRET` | Stripe Dashboard → Developers → Webhooks → [endpoint] → Signing secret | `.env.local` |
-
-## Account Setup
-
-- [ ] **Create Stripe account** (if needed)
-  - URL: https://dashboard.stripe.com/register
-  - Skip if: Already have Stripe account
-
-## Dashboard Configuration
-
-- [ ] **Create webhook endpoint**
-  - Location: Stripe Dashboard → Developers → Webhooks → Add endpoint
-  - Endpoint URL: `https://[your-domain]/api/webhooks/stripe`
-  - Events to send:
-    - `checkout.session.completed`
-    - `customer.subscription.created`
-    - `customer.subscription.updated`
-    - `customer.subscription.deleted`
-
-- [ ] **Create products and prices** (if using subscription tiers)
-  - Location: Stripe Dashboard → Products → Add product
-  - Create each subscription tier
-  - Copy Price IDs to:
-    - `STRIPE_STARTER_PRICE_ID`
-    - `STRIPE_PRO_PRICE_ID`
-
-## Local Development
-
-For local webhook testing:
-```bash
-stripe listen --forward-to localhost:3000/api/webhooks/stripe
-```
-Use the webhook signing secret from CLI output (starts with `whsec_`).
-
-## Verification
-
-After completing setup:
-
-```bash
-# Check env vars are set
-grep STRIPE .env.local
-
-# Verify build passes
-npm run build
-
-# Test webhook endpoint (should return 400 bad signature, not 500 crash)
-curl -X POST http://localhost:3000/api/webhooks/stripe \
-  -H "Content-Type: application/json" \
-  -d '{}'
-```
-
-Expected: Build passes, webhook returns 400 (signature validation working).
-
----
-
-**Once all items complete:** Mark status as "Complete" at top of file.
-```
-</stripe_example>
-
-<supabase_example>
-```markdown
-# Phase 2: User Setup Required
-
-**Generated:** 2025-01-14
-**Phase:** 02-authentication
-**Status:** Incomplete
-
-Complete these items for Supabase Auth to function.
-
-## Environment Variables
-
-| Status | Variable | Source | Add to |
-|--------|----------|--------|--------|
-| [ ] | `NEXT_PUBLIC_SUPABASE_URL` | Supabase Dashboard → Settings → API → Project URL | `.env.local` |
-| [ ] | `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase Dashboard → Settings → API → anon public | `.env.local` |
-| [ ] | `SUPABASE_SERVICE_ROLE_KEY` | Supabase Dashboard → Settings → API → service_role | `.env.local` |
-
-## Account Setup
-
-- [ ] **Create Supabase project**
-  - URL: https://supabase.com/dashboard/new
-  - Skip if: Already have project for this app
-
-## Dashboard Configuration
-
-- [ ] **Enable Email Auth**
-  - Location: Supabase Dashboard → Authentication → Providers
-  - Enable: Email provider
-  - Configure: Confirm email (on/off based on preference)
-
-- [ ] **Configure OAuth providers** (if using social login)
-  - Location: Supabase Dashboard → Authentication → Providers
-  - For Google: Add Client ID and Secret from Google Cloud Console
-  - For GitHub: Add Client ID and Secret from GitHub OAuth Apps
-
-## Verification
-
-After completing setup:
-
-```bash
-# Check env vars
-grep SUPABASE .env.local
-
-# Verify connection (run in project directory)
-npx supabase status
-```
-
----
-
-**Once all items complete:** Mark status as "Complete" at top of file.
-```
-</supabase_example>
-
-<sendgrid_example>
-```markdown
-# Phase 5: User Setup Required
-
-**Generated:** 2025-01-14
-**Phase:** 05-notifications
-**Status:** Incomplete
-
-Complete these items for SendGrid email to function.
-
-## Environment Variables
-
-| Status | Variable | Source | Add to |
-|--------|----------|--------|--------|
-| [ ] | `SENDGRID_API_KEY` | SendGrid Dashboard → Settings → API Keys → Create API Key | `.env.local` |
-| [ ] | `SENDGRID_FROM_EMAIL` | Your verified sender email address | `.env.local` |
-
-## Account Setup
-
-- [ ] **Create SendGrid account**
-  - URL: https://signup.sendgrid.com/
-  - Skip if: Already have account
-
-## Dashboard Configuration
-
-- [ ] **Verify sender identity**
-  - Location: SendGrid Dashboard → Settings → Sender Authentication
-  - Option 1: Single Sender Verification (quick, for dev)
-  - Option 2: Domain Authentication (production)
-
-- [ ] **Create API Key**
-  - Location: SendGrid Dashboard → Settings → API Keys → Create API Key
-  - Permission: Restricted Access → Mail Send (Full Access)
-  - Copy key immediately (shown only once)
-
-## Verification
-
-After completing setup:
-
-```bash
-# Check env var
-grep SENDGRID .env.local
-
-# Test email sending (replace with your test email)
-curl -X POST http://localhost:3000/api/test-email \
-  -H "Content-Type: application/json" \
-  -d '{"to": "your@email.com"}'
-```
-
----
-
-**Once all items complete:** Mark status as "Complete" at top of file.
-```
-</sendgrid_example>
-
----
-
-## Guidelines
-
-**Never include:** Actual secret values. Steps Claude can automate (package installs, code changes).
-
-**Naming:** `{phase}-USER-SETUP.md` matches the phase number pattern.
-**Status tracking:** User marks checkboxes and updates status line when complete.
-**Searchability:** `grep -r "USER-SETUP" .planning/` finds all phases with user requirements.