mindforge-cc 8.2.0 → 10.0.0

package/docs/Templates/Codebase/concerns.md

@@ -1,310 +0,0 @@
-# Codebase Concerns Template
-
-Template for `.mindforge/codebase/CONCERNS.md` - captures known issues and areas requiring care.
-
-**Purpose:** Surface actionable warnings about the codebase. Focused on "what to watch out for when making changes."
-
----
-
-## File Template
-
-```markdown
-# Codebase Concerns
-
-**Analysis Date:** [YYYY-MM-DD]
-
-## Tech Debt
-
-**[Area/Component]:**
-- Issue: [What's the shortcut/workaround]
-- Why: [Why it was done this way]
-- Impact: [What breaks or degrades because of it]
-- Fix approach: [How to properly address it]
-
-**[Area/Component]:**
-- Issue: [What's the shortcut/workaround]
-- Why: [Why it was done this way]
-- Impact: [What breaks or degrades because of it]
-- Fix approach: [How to properly address it]
-
-## Known Bugs
-
-**[Bug description]:**
-- Symptoms: [What happens]
-- Trigger: [How to reproduce]
-- Workaround: [Temporary mitigation if any]
-- Root cause: [If known]
-- Blocked by: [If waiting on something]
-
-**[Bug description]:**
-- Symptoms: [What happens]
-- Trigger: [How to reproduce]
-- Workaround: [Temporary mitigation if any]
-- Root cause: [If known]
-
-## Security Considerations
-
-**[Area requiring security care]:**
-- Risk: [What could go wrong]
-- Current mitigation: [What's in place now]
-- Recommendations: [What should be added]
-
-**[Area requiring security care]:**
-- Risk: [What could go wrong]
-- Current mitigation: [What's in place now]
-- Recommendations: [What should be added]
-
-## Performance Bottlenecks
-
-**[Slow operation/endpoint]:**
-- Problem: [What's slow]
-- Measurement: [Actual numbers: "500ms p95", "2s load time"]
-- Cause: [Why it's slow]
-- Improvement path: [How to speed it up]
-
-**[Slow operation/endpoint]:**
-- Problem: [What's slow]
-- Measurement: [Actual numbers]
-- Cause: [Why it's slow]
-- Improvement path: [How to speed it up]
-
-## Fragile Areas
-
-**[Component/Module]:**
-- Why fragile: [What makes it break easily]
-- Common failures: [What typically goes wrong]
-- Safe modification: [How to change it without breaking]
-- Test coverage: [Is it tested? Gaps?]
-
-**[Component/Module]:**
-- Why fragile: [What makes it break easily]
-- Common failures: [What typically goes wrong]
-- Safe modification: [How to change it without breaking]
-- Test coverage: [Is it tested? Gaps?]
-
-## Scaling Limits
-
-**[Resource/System]:**
-- Current capacity: [Numbers: "100 req/sec", "10k users"]
-- Limit: [Where it breaks]
-- Symptoms at limit: [What happens]
-- Scaling path: [How to increase capacity]
-
-## Dependencies at Risk
-
-**[Package/Service]:**
-- Risk: [e.g., "deprecated", "unmaintained", "breaking changes coming"]
-- Impact: [What breaks if it fails]
-- Migration plan: [Alternative or upgrade path]
-
-## Missing Critical Features
-
-**[Feature gap]:**
-- Problem: [What's missing]
-- Current workaround: [How users cope]
-- Blocks: [What can't be done without it]
-- Implementation complexity: [Rough effort estimate]
-
-## Test Coverage Gaps
-
-**[Untested area]:**
-- What's not tested: [Specific functionality]
-- Risk: [What could break unnoticed]
-- Priority: [High/Medium/Low]
-- Difficulty to test: [Why it's not tested yet]
-
----
-
-*Concerns audit: [date]*
-*Update as issues are fixed or new ones discovered*
-```
-
-<good_examples>
-```markdown
-# Codebase Concerns
-
-**Analysis Date:** 2025-01-20
-
-## Tech Debt
-
-**Database queries in React components:**
-- Issue: Direct Supabase queries in 15+ page components instead of server actions
-- Files: `app/dashboard/page.tsx`, `app/profile/page.tsx`, `app/courses/[id]/page.tsx`, `app/settings/page.tsx` (and 11 more in `app/`)
-- Why: Rapid prototyping during MVP phase
-- Impact: Can't implement RLS properly, exposes DB structure to client
-- Fix approach: Move all queries to server actions in `app/actions/`, add proper RLS policies
-
-**Manual webhook signature validation:**
-- Issue: Copy-pasted Stripe webhook verification code in 3 different endpoints
-- Files: `app/api/webhooks/stripe/route.ts`, `app/api/webhooks/checkout/route.ts`, `app/api/webhooks/subscription/route.ts`
-- Why: Each webhook added ad-hoc without abstraction
-- Impact: Easy to miss verification in new webhooks (security risk)
-- Fix approach: Create shared `lib/stripe/validate-webhook.ts` middleware
-
-## Known Bugs
-
-**Race condition in subscription updates:**
-- Symptoms: User shows as "free" tier for 5-10 seconds after successful payment
-- Trigger: Fast navigation after Stripe checkout redirect, before webhook processes
-- Files: `app/checkout/success/page.tsx` (redirect handler), `app/api/webhooks/stripe/route.ts` (webhook)
-- Workaround: Stripe webhook eventually updates status (self-heals)
-- Root cause: Webhook processing slower than user navigation, no optimistic UI update
-- Fix: Add polling in `app/checkout/success/page.tsx` after redirect
-
-**Inconsistent session state after logout:**
-- Symptoms: User redirected to /dashboard after logout instead of /login
-- Trigger: Logout via button in mobile nav (desktop works fine)
-- File: `components/MobileNav.tsx` (line ~45, logout handler)
-- Workaround: Manual URL navigation to /login works
-- Root cause: Mobile nav component not awaiting supabase.auth.signOut()
-- Fix: Add await to logout handler in `components/MobileNav.tsx`
-
-## Security Considerations
-
-**Admin role check client-side only:**
-- Risk: Admin dashboard pages check isAdmin from Supabase client, no server verification
-- Files: `app/admin/page.tsx`, `app/admin/users/page.tsx`, `components/AdminGuard.tsx`
-- Current mitigation: None (relying on UI hiding)
-- Recommendations: Add middleware to admin routes in `middleware.ts`, verify role server-side
-
-**Unvalidated file uploads:**
-- Risk: Users can upload any file type to avatar bucket (no size/type validation)
-- File: `components/AvatarUpload.tsx` (upload handler)
-- Current mitigation: Supabase bucket limits to 2MB (configured in dashboard)
-- Recommendations: Add file type validation (image/* only) in `lib/storage/validate.ts`
-
-## Performance Bottlenecks
-
-**/api/courses endpoint:**
-- Problem: Fetching all courses with nested lessons and authors
-- File: `app/api/courses/route.ts`
-- Measurement: 1.2s p95 response time with 50+ courses
-- Cause: N+1 query pattern (separate query per course for lessons)
-- Improvement path: Use Prisma include to eager-load lessons in `lib/db/courses.ts`, add Redis caching
-
-**Dashboard initial load:**
-- Problem: Waterfall of 5 serial API calls on mount
-- File: `app/dashboard/page.tsx`
-- Measurement: 3.5s until interactive on slow 3G
-- Cause: Each component fetches own data independently
-- Improvement path: Convert to Server Component with single parallel fetch
-
-## Fragile Areas
-
-**Authentication middleware chain:**
-- File: `middleware.ts`
-- Why fragile: 4 different middleware functions run in specific order (auth -> role -> subscription -> logging)
-- Common failures: Middleware order change breaks everything, hard to debug
-- Safe modification: Add tests before changing order, document dependencies in comments
-- Test coverage: No integration tests for middleware chain (only unit tests)
-
-**Stripe webhook event handling:**
-- File: `app/api/webhooks/stripe/route.ts`
-- Why fragile: Giant switch statement with 12 event types, shared transaction logic
-- Common failures: New event type added without handling, partial DB updates on error
-- Safe modification: Extract each event handler to `lib/stripe/handlers/*.ts`
-- Test coverage: Only 3 of 12 event types have tests
-
-## Scaling Limits
-
-**Supabase Free Tier:**
-- Current capacity: 500MB database, 1GB file storage, 2GB bandwidth/month
-- Limit: ~5000 users estimated before hitting limits
-- Symptoms at limit: 429 rate limit errors, DB writes fail
-- Scaling path: Upgrade to Pro ($25/mo) extends to 8GB DB, 100GB storage
-
-**Server-side render blocking:**
-- Current capacity: ~50 concurrent users before slowdown
-- Limit: Vercel Hobby plan (10s function timeout, 100GB-hrs/mo)
-- Symptoms at limit: 504 gateway timeouts on course pages
-- Scaling path: Upgrade to Vercel Pro ($20/mo), add edge caching
-
-## Dependencies at Risk
-
-**react-hot-toast:**
-- Risk: Unmaintained (last update 18 months ago), React 19 compatibility unknown
-- Impact: Toast notifications break, no graceful degradation
-- Migration plan: Switch to sonner (actively maintained, similar API)
-
-## Missing Critical Features
-
-**Payment failure handling:**
-- Problem: No retry mechanism or user notification when subscription payment fails
-- Current workaround: Users manually re-enter payment info (if they notice)
-- Blocks: Can't retain users with expired cards, no dunning process
-- Implementation complexity: Medium (Stripe webhooks + email flow + UI)
-
-**Course progress tracking:**
-- Problem: No persistent state for which lessons completed
-- Current workaround: Users manually track progress
-- Blocks: Can't show completion percentage, can't recommend next lesson
-- Implementation complexity: Low (add completed_lessons junction table)
-
-## Test Coverage Gaps
-
-**Payment flow end-to-end:**
-- What's not tested: Full Stripe checkout -> webhook -> subscription activation flow
-- Risk: Payment processing could break silently (has happened twice)
-- Priority: High
-- Difficulty to test: Need Stripe test fixtures and webhook simulation setup
-
-**Error boundary behavior:**
-- What's not tested: How app behaves when components throw errors
-- Risk: White screen of death for users, no error reporting
-- Priority: Medium
-- Difficulty to test: Need to intentionally trigger errors in test environment
-
----
-
-*Concerns audit: 2025-01-20*
-*Update as issues are fixed or new ones discovered*
-```
-</good_examples>
-
-<guidelines>
-**What belongs in CONCERNS.md:**
-- Tech debt with clear impact and fix approach
-- Known bugs with reproduction steps
-- Security gaps and mitigation recommendations
-- Performance bottlenecks with measurements
-- Fragile code that breaks easily
-- Scaling limits with numbers
-- Dependencies that need attention
-- Missing features that block workflows
-- Test coverage gaps
-
-**What does NOT belong here:**
-- Opinions without evidence ("code is messy")
-- Complaints without solutions ("auth sucks")
-- Future feature ideas (that's for product planning)
-- Normal TODOs (those live in code comments)
-- Architectural decisions that are working fine
-- Minor code style issues
-
-**When filling this template:**
-- **Always include file paths** - Concerns without locations are not actionable. Use backticks: `src/file.ts`
-- Be specific with measurements ("500ms p95" not "slow")
-- Include reproduction steps for bugs
-- Suggest fix approaches, not just problems
-- Focus on actionable items
-- Prioritize by risk/impact
-- Update as issues get resolved
-- Add new concerns as discovered
-
-**Tone guidelines:**
-- Professional, not emotional ("N+1 query pattern" not "terrible queries")
-- Solution-oriented ("Fix: add index" not "needs fixing")
-- Risk-focused ("Could expose user data" not "security is bad")
-- Factual ("3.5s load time" not "really slow")
-
-**Useful for phase planning when:**
-- Deciding what to work on next
-- Estimating risk of changes
-- Understanding where to be careful
-- Prioritizing improvements
-- Onboarding new MindForge contexts
-- Planning refactoring work
-
-**How this gets populated:**
-Explore agents detect these during codebase mapping. Manual additions welcome for human-discovered issues. This is living documentation, not a complaint list.
-</guidelines>

package/docs/Templates/Codebase/conventions.md

@@ -1,307 +0,0 @@
-# Coding Conventions Template
-
-Template for `.mindforge/codebase/CONVENTIONS.md` - captures coding style and patterns.
-
-**Purpose:** Document how code is written in this codebase. Prescriptive guide for MindForge to match existing style.
-
----
-
-## File Template
-
-```markdown
-# Coding Conventions
-
-**Analysis Date:** [YYYY-MM-DD]
-
-## Naming Patterns
-
-**Files:**
-- [Pattern: e.g., "kebab-case for all files"]
-- [Test files: e.g., "*.test.ts alongside source"]
-- [Components: e.g., "PascalCase.tsx for React components"]
-
-**Functions:**
-- [Pattern: e.g., "camelCase for all functions"]
-- [Async: e.g., "no special prefix for async functions"]
-- [Handlers: e.g., "handleEventName for event handlers"]
-
-**Variables:**
-- [Pattern: e.g., "camelCase for variables"]
-- [Constants: e.g., "UPPER_SNAKE_CASE for constants"]
-- [Private: e.g., "_prefix for private members" or "no prefix"]
-
-**Types:**
-- [Interfaces: e.g., "PascalCase, no I prefix"]
-- [Types: e.g., "PascalCase for type aliases"]
-- [Enums: e.g., "PascalCase for enum name, UPPER_CASE for values"]
-
-## Code Style
-
-**Formatting:**
-- [Tool: e.g., "Prettier with config in .prettierrc"]
-- [Line length: e.g., "100 characters max"]
-- [Quotes: e.g., "single quotes for strings"]
-- [Semicolons: e.g., "required" or "omitted"]
-
-**Linting:**
-- [Tool: e.g., "ESLint with eslint.config.js"]
-- [Rules: e.g., "extends airbnb-base, no console in production"]
-- [Run: e.g., "npm run lint"]
-
-## Import Organization
-
-**Order:**
-1. [e.g., "External packages (react, express, etc.)"]
-2. [e.g., "Internal modules (@/lib, @/components)"]
-3. [e.g., "Relative imports (., ..)"]
-4. [e.g., "Type imports (import type {})"]
-
-**Grouping:**
-- [Blank lines: e.g., "blank line between groups"]
-- [Sorting: e.g., "alphabetical within each group"]
-
-**Path Aliases:**
-- [Aliases used: e.g., "@/ for src/, @components/ for src/components/"]
-
-## Error Handling
-
-**Patterns:**
-- [Strategy: e.g., "throw errors, catch at boundaries"]
-- [Custom errors: e.g., "extend Error class, named *Error"]
-- [Async: e.g., "use try/catch, no .catch() chains"]
-
-**Error Types:**
-- [When to throw: e.g., "invalid input, missing dependencies"]
-- [When to return: e.g., "expected failures return Result<T, E>"]
-- [Logging: e.g., "log error with context before throwing"]
-
-## Logging
-
-**Framework:**
-- [Tool: e.g., "console.log, pino, winston"]
-- [Levels: e.g., "debug, info, warn, error"]
-
-**Patterns:**
-- [Format: e.g., "structured logging with context object"]
-- [When: e.g., "log state transitions, external calls"]
-- [Where: e.g., "log at service boundaries, not in utils"]
-
-## Comments
-
-**When to Comment:**
-- [e.g., "explain why, not what"]
-- [e.g., "document business logic, algorithms, edge cases"]
-- [e.g., "avoid obvious comments like // increment counter"]
-
-**JSDoc/TSDoc:**
-- [Usage: e.g., "required for public APIs, optional for internal"]
-- [Format: e.g., "use @param, @returns, @throws tags"]
-
-**TODO Comments:**
-- [Pattern: e.g., "// TODO(username): description"]
-- [Tracking: e.g., "link to issue number if available"]
-
-## Function Design
-
-**Size:**
-- [e.g., "keep under 50 lines, extract helpers"]
-
-**Parameters:**
-- [e.g., "max 3 parameters, use object for more"]
-- [e.g., "destructure objects in parameter list"]
-
-**Return Values:**
-- [e.g., "explicit returns, no implicit undefined"]
-- [e.g., "return early for guard clauses"]
-
-## Module Design
-
-**Exports:**
-- [e.g., "named exports preferred, default exports for React components"]
-- [e.g., "export from index.ts for public API"]
-
-**Barrel Files:**
-- [e.g., "use index.ts to re-export public API"]
-- [e.g., "avoid circular dependencies"]
-
----
-
-*Convention analysis: [date]*
-*Update when patterns change*
-```
-
-<good_examples>
-```markdown
-# Coding Conventions
-
-**Analysis Date:** 2025-01-20
-
-## Naming Patterns
-
-**Files:**
-- kebab-case for all files (command-handler.ts, user-service.ts)
-- *.test.ts alongside source files
-- index.ts for barrel exports
-
-**Functions:**
-- camelCase for all functions
-- No special prefix for async functions
-- handleEventName for event handlers (handleClick, handleSubmit)
-
-**Variables:**
-- camelCase for variables
-- UPPER_SNAKE_CASE for constants (MAX_RETRIES, API_BASE_URL)
-- No underscore prefix (no private marker in TS)
-
-**Types:**
-- PascalCase for interfaces, no I prefix (User, not IUser)
-- PascalCase for type aliases (UserConfig, ResponseData)
-- PascalCase for enum names, UPPER_CASE for values (Status.PENDING)
-
-## Code Style
-
-**Formatting:**
-- Prettier with .prettierrc
-- 100 character line length
-- Single quotes for strings
-- Semicolons required
-- 2 space indentation
-
-**Linting:**
-- ESLint with eslint.config.js
-- Extends @typescript-eslint/recommended
-- No console.log in production code (use logger)
-- Run: npm run lint
-
-## Import Organization
-
-**Order:**
-1. External packages (react, express, commander)
-2. Internal modules (@/lib, @/services)
-3. Relative imports (./utils, ../types)
-4. Type imports (import type { User })
-
-**Grouping:**
-- Blank line between groups
-- Alphabetical within each group
-- Type imports last within each group
-
-**Path Aliases:**
-- @/ maps to src/
-- No other aliases defined
-
-## Error Handling
-
-**Patterns:**
-- Throw errors, catch at boundaries (route handlers, main functions)
-- Extend Error class for custom errors (ValidationError, NotFoundError)
-- Async functions use try/catch, no .catch() chains
-
-**Error Types:**
-- Throw on invalid input, missing dependencies, invariant violations
-- Log error with context before throwing: logger.error({ err, userId }, 'Failed to process')
-- Include cause in error message: new Error('Failed to X', { cause: originalError })
-
-## Logging
-
-**Framework:**
-- pino logger instance exported from lib/logger.ts
-- Levels: debug, info, warn, error (no trace)
-
-**Patterns:**
-- Structured logging with context: logger.info({ userId, action }, 'User action')
-- Log at service boundaries, not in utility functions
-- Log state transitions, external API calls, errors
-- No console.log in committed code
-
-## Comments
-
-**When to Comment:**
-- Explain why, not what: // Retry 3 times because API has transient failures
-- Document business rules: // Users must verify email within 24 hours
-- Explain non-obvious algorithms or workarounds
-- Avoid obvious comments: // set count to 0
-
-**JSDoc/TSDoc:**
-- Required for public API functions
-- Optional for internal functions if signature is self-explanatory
-- Use @param, @returns, @throws tags
-
-**TODO Comments:**
-- Format: // TODO: description (no username, using git blame)
-- Link to issue if exists: // TODO: Fix race condition (issue #123)
-
-## Function Design
-
-**Size:**
-- Keep under 50 lines
-- Extract helpers for complex logic
-- One level of abstraction per function
-
-**Parameters:**
-- Max 3 parameters
-- Use options object for 4+ parameters: function create(options: CreateOptions)
-- Destructure in parameter list: function process({ id, name }: ProcessParams)
-
-**Return Values:**
-- Explicit return statements
-- Return early for guard clauses
-- Use Result<T, E> type for expected failures
-
-## Module Design
-
-**Exports:**
-- Named exports preferred
-- Default exports only for React components
-- Export public API from index.ts barrel files
-
-**Barrel Files:**
-- index.ts re-exports public API
-- Keep internal helpers private (don't export from index)
-- Avoid circular dependencies (import from specific files if needed)
-
----
-
-*Convention analysis: 2025-01-20*
-*Update when patterns change*
-```
-</good_examples>
-
-<guidelines>
-**What belongs in CONVENTIONS.md:**
-- Naming patterns observed in the codebase
-- Formatting rules (Prettier config, linting rules)
-- Import organization patterns
-- Error handling strategy
-- Logging approach
-- Comment conventions
-- Function and module design patterns
-
-**What does NOT belong here:**
-- Architecture decisions (that's ARCHITECTURE.md)
-- Technology choices (that's STACK.md)
-- Test patterns (that's TESTING.md)
-- File organization (that's STRUCTURE.md)
-
-**When filling this template:**
-- Check .prettierrc, .eslintrc, or similar config files
-- Examine 5-10 representative source files for patterns
-- Look for consistency: if 80%+ follows a pattern, document it
-- Be prescriptive: "Use X" not "Sometimes Y is used"
-- Note deviations: "Legacy code uses Y, new code should use X"
-- Keep under ~150 lines total
-
-**Useful for phase planning when:**
-- Writing new code (match existing style)
-- Adding features (follow naming patterns)
-- Refactoring (apply consistent conventions)
-- Code review (check against documented patterns)
-- Onboarding (understand style expectations)
-
-**Analysis approach:**
-- Scan src/ directory for file naming patterns
-- Check package.json scripts for lint/format commands
-- Read 5-10 files to identify function naming, error handling
-- Look for config files (.prettierrc, eslint.config.js)
-- Note patterns in imports, comments, function signatures
-</guidelines>