sublation-os 1.0.0

package/.claude/commands/sublation-os/review-v2.md

@@ -0,0 +1,701 @@
+---
+argument-hint: [file-path or directory]
+description: Comprehensive code review using Chain of Thought analysis and ReAct investigation
+---
+
+You are conducting a comprehensive code review using **Chain of Thought (CoT)** reasoning for systematic analysis and **ReAct** for investigating suspicious patterns.
+
+## Code to Review
+$message
+
+---
+
+## Review Process
+
+### Phase 1: Understanding (Chain of Thought)
+
+Before identifying issues, deeply understand the code.
+
+**Think through these questions systematically:**
+
+1. **Purpose**: What is this code supposed to do?
+2. **Context**: How does it fit into the larger system?
+3. **Complexity**: What are the most complex parts?
+4. **Critical paths**: What are the high-risk areas?
+5. **Stakeholders**: Who uses or depends on this code?
+
+**Document your understanding:**
+```markdown
+## Code Understanding
+
+**Purpose**: {1-2 sentence summary}
+
+**Key Components**:
+- {Component 1}: {What it does}
+- {Component 2}: {What it does}
+
+**Critical Paths**:
+- {Path 1}: {Why it's critical}
+- {Path 2}: {Why it's critical}
+
+**Complexity Hotspots**:
+- {Location 1}: {Why it's complex}
+```
+
+---
+
+### Phase 2: Load Context
+
+Before reviewing, load relevant context:
+
+#### User Standards
+Read applicable standards from `.sublation-os/standards/`:
+- For backend code: Read `backend/*.md`
+- For frontend code: Read `frontend/*.md`
+- For all code: Read `global/*.md`
+- For tests: Read `testing/*.md`
+
+#### Past Learnings
+Read relevant memory files from `.sublation-os/memory/`:
+- Start with `index.md` to identify relevant categories
+- Read category-specific lessons (backend/frontend/testing/architecture)
+- Look for:
+  - Known anti-patterns in this codebase
+  - Preferred patterns and conventions
+  - Security gotchas
+  - Performance lessons
+
+---
+
+### Phase 3: Multi-Dimensional Analysis (Chain of Thought)
+
+Analyze the code across multiple dimensions. For each dimension, **think step by step** through potential issues.
+
+#### Dimension 1: Correctness 🎯
+
+**THINK**: Does this code do what it's supposed to do?
+
+Analyze systematically:
+- **Logic correctness**: Are conditions correct? Any off-by-one errors?
+- **Edge cases**: What happens with null, empty, or unexpected inputs?
+- **Error handling**: Are errors caught and handled appropriately?
+- **Data integrity**: Could data be corrupted or lost?
+- **Race conditions**: Any concurrency issues?
+
+**For each issue found, use ReAct to investigate:**
+
+**THOUGHT**: This loop condition looks suspicious - it might skip the last element
+
+**ACTION**: Check the loop boundaries and test with example values
+
+**OBSERVATION**: Confirmed - loop uses `<` instead of `<=`, missing last item
+
+---
+
+#### Dimension 2: Security 🔒
+
+**THINK**: What could an attacker exploit?
+
+Use the STRIDE threat model:
+- **Spoofing**: Can authentication be bypassed?
+- **Tampering**: Can data be modified maliciously?
+- **Repudiation**: Can actions be denied?
+- **Information Disclosure**: Can sensitive data leak?
+- **Denial of Service**: Can the service be disrupted?
+- **Elevation of Privilege**: Can permissions be bypassed?
+
+**Common vulnerabilities to check:**
+- SQL Injection (unsanitized queries)
+- XSS (unescaped output)
+- CSRF (missing tokens)
+- Authentication bypass
+- Authorization flaws
+- Insecure dependencies
+- Hardcoded secrets
+- Path traversal
+- Command injection
+- Insecure deserialization
+
+**For each security concern:**
+
+**THOUGHT**: This SQL query uses string concatenation - potential SQL injection
+
+**ACTION**: Search codebase for the sanitization pattern used elsewhere
+
+**OBSERVATION**: Other queries use parameterized queries - this should too
+
+---
+
+#### Dimension 3: Performance ⚡
+
+**THINK**: Where are the bottlenecks?
+
+Analyze systematically:
+- **Algorithmic complexity**: O(n²) where O(n) is possible?
+- **Database queries**: N+1 queries? Missing indexes?
+- **Caching**: Could results be cached?
+- **Memory usage**: Unnecessary allocations? Memory leaks?
+- **Network calls**: Too many API requests? Parallelizable?
+- **Blocking operations**: Synchronous where async would help?
+
+**For each performance issue:**
+
+**THOUGHT**: This loads all records into memory - could be 100k+ rows
+
+**ACTION**: Check if pagination or streaming is used elsewhere
+
+**OBSERVATION**: Similar endpoints use cursor pagination - apply here
+
+---
+
+#### Dimension 4: Maintainability 🔧
+
+**THINK**: How hard is this to understand and modify?
+
+Evaluate:
+- **Readability**: Is the code clear? Are names descriptive?
+- **Complexity**: Are functions too long? Too many branches?
+- **Duplication**: Is code repeated unnecessarily?
+- **Documentation**: Are complex parts explained?
+- **Consistency**: Does it follow codebase conventions?
+- **Dependencies**: Are they necessary? Up to date?
+- **Technical debt**: What shortcuts were taken?
+
+**Apply codebase patterns:**
+
+**THOUGHT**: This function is 300 lines - violates the codebase pattern
+
+**ACTION**: Check past learnings for preferred function size
+
+**OBSERVATION**: Memory system shows 50-line limit with extraction pattern
+
+---
+
+#### Dimension 5: Testing 🧪
+
+**THINK**: How testable is this code? What's the test coverage?
+
+Analyze:
+- **Testability**: Are dependencies injectable? Functions pure?
+- **Coverage**: Are critical paths tested?
+- **Test quality**: Do tests verify behavior or implementation?
+- **Edge cases**: Are error conditions tested?
+- **Brittleness**: Will tests break with minor refactoring?
+
+**Check against standards:**
+
+**THOUGHT**: No tests found for this critical business logic
+
+**ACTION**: Read testing standards to see requirements
+
+**OBSERVATION**: Standards require >80% coverage for services - needs tests
+
+---
+
+#### Dimension 6: Architecture 🏗️
+
+**THINK**: Does this follow good design principles?
+
+Evaluate:
+- **SOLID principles**: Single responsibility, etc.
+- **Separation of concerns**: Are layers properly separated?
+- **Coupling**: Is code tightly coupled?
+- **Cohesion**: Do related things belong together?
+- **Patterns**: Are appropriate patterns used?
+- **Extensibility**: Easy to extend without modification?
+
+**Consider past learnings:**
+
+**THOUGHT**: This controller has database access - breaks layering
+
+**ACTION**: Check architecture lessons for preferred pattern
+
+**OBSERVATION**: Codebase uses repository pattern - should apply here
+
+---
+
+#### Dimension 7: Standards Compliance 📋
+
+**THINK**: Does this follow the user's documented standards?
+
+Check against `.sublation-os/standards/`:
+- **Naming conventions**: Variables, functions, files
+- **Code style**: Indentation, formatting, structure
+- **Error handling**: Patterns used
+- **Validation**: Input validation approach
+- **API design**: REST conventions, response formats
+- **Component structure**: File organization
+
+**Flag violations:**
+
+**THOUGHT**: Error handling doesn't match standards
+
+**ACTION**: Read global/error-handling.md for requirements
+
+**OBSERVATION**: Standards require try-catch with structured logging - missing
+
+---
+
+### Phase 4: Pattern Investigation (ReAct)
+
+For any suspicious patterns, investigate systematically:
+
+**Example:**
+
+**THOUGHT**: I see several async operations that could run in parallel but are sequential
+
+**ACTION**: Calculate potential time savings - 3 serial 100ms calls = 300ms
+
+**OBSERVATION**: Could reduce to 100ms with Promise.all() - significant improvement
+
+**THOUGHT**: Before recommending, check if there are dependencies between calls
+
+**ACTION**: Analyze data flow between the async operations
+
+**OBSERVATION**: No dependencies found - safe to parallelize
+
+---
+
+## Review Report Structure
+
+Generate a comprehensive report following this structure:
+
+```markdown
+# Code Review Report
+
+**Reviewed**: {file paths}
+**Date**: {current date}
+**Reviewer**: review-v2 (AI-assisted)
+**Lines of Code**: {approximate count}
+
+---
+
+## Executive Summary
+
+{2-3 sentence overview of code quality and key findings}
+
+**Overall Assessment**:
+- Correctness: ⭐⭐⭐⭐⭐ (5/5)
+- Security: ⭐⭐⭐⭐⬜ (4/5)
+- Performance: ⭐⭐⭐⬜⬜ (3/5)
+- Maintainability: ⭐⭐⭐⭐⬜ (4/5)
+- Testing: ⭐⭐⬜⬜⬜ (2/5)
+- Architecture: ⭐⭐⭐⭐⭐ (5/5)
+- Standards: ⭐⭐⭐⭐⬜ (4/5)
+
+**Recommendation**: ✅ Approve with changes | ⚠️ Needs significant work | ❌ Major issues
+
+---
+
+## Critical Issues 🔴
+
+Issues that MUST be fixed before merging.
+
+### Issue 1: SQL Injection Vulnerability
+**Location**: `src/controllers/userController.js:45`
+**Severity**: 🔴 Critical - Security
+**Category**: Security - SQL Injection
+
+**Problem**:
+```javascript
+// ❌ CURRENT (Line 45)
+const query = `SELECT * FROM users WHERE id = ${userId}`;
+db.query(query);
+```
+
+**Why this is critical**:
+An attacker can inject SQL through the userId parameter, potentially accessing or deleting all database records.
+
+**Recommended fix**:
+```javascript
+// ✅ RECOMMENDED
+const query = 'SELECT * FROM users WHERE id = ?';
+db.query(query, [userId]);
+```
+
+**Reasoning**: Parameterized queries prevent SQL injection by treating input as data, not executable code. This pattern is used throughout the codebase (see src/models/User.js:23).
+
+**THOUGHT process**: Found string concatenation in SQL query → Checked if input is sanitized → Not sanitized → Checked codebase for correct pattern → Found parameterized query pattern.
+
+---
+
+### Issue 2: {Next critical issue}
+{Repeat structure}
+
+---
+
+## High Priority Issues 🟠
+
+Issues that should be fixed soon.
+
+### Issue 1: N+1 Query Problem
+**Location**: `src/services/orderService.js:78-85`
+**Severity**: 🟠 High - Performance
+**Category**: Performance - Database
+
+**Problem**:
+```javascript
+// ❌ CURRENT (Lines 78-85)
+const orders = await Order.findAll();
+for (const order of orders) {
+  order.items = await OrderItem.findByOrderId(order.id); // N queries
+}
+```
+
+**Impact**: With 1000 orders, this executes 1001 queries (1 + 1000). Response time: ~5-10 seconds.
+
+**Recommended fix**:
+```javascript
+// ✅ RECOMMENDED
+const orders = await Order.findAll({
+  include: [{
+    model: OrderItem,
+    as: 'items'
+  }]
+});
+```
+
+**Performance gain**: Reduces to 1 query. Expected response time: ~50-100ms (50-100x improvement).
+
+**Reasoning**: This ORM supports eager loading. Pattern used in src/services/productService.js:45. Past learnings (backend-lessons.md Entry 12) specifically flag N+1 queries as common problem.
+
+**Alternative solution**: Could use a single JOIN query if ORM isn't flexible enough, but ORM solution is cleaner.
+
+---
+
+### Issue 2: {Next high priority issue}
+{Repeat structure}
+
+---
+
+## Medium Priority Issues 🟡
+
+Issues that improve quality but aren't urgent.
+
+### Issue 1: Function Too Complex
+**Location**: `src/utils/validator.js:120-280`
+**Severity**: 🟡 Medium - Maintainability
+**Category**: Maintainability - Complexity
+
+**Problem**:
+- Function is 160 lines long
+- Cyclomatic complexity: ~25 (threshold: 10)
+- Difficult to test and understand
+
+**Reasoning**: This violates the codebase convention (past learnings show 50-line function limit) and makes future modifications risky.
+
+**Recommended refactoring**:
+```javascript
+// ✅ SPLIT INTO FOCUSED FUNCTIONS
+function validateUser(data) {
+  validateRequiredFields(data);
+  validateEmail(data.email);
+  validatePassword(data.password);
+  validateAge(data.age);
+  return true;
+}
+
+function validateRequiredFields(data) {
+  const required = ['email', 'password', 'name'];
+  for (const field of required) {
+    if (!data[field]) throw new Error(`${field} is required`);
+  }
+}
+```
+
+**Benefits**:
+- Each function has single responsibility
+- Easier to test individual validators
+- More reusable
+- Clearer intent
+
+---
+
+## Low Priority Issues 🟢
+
+Nice-to-have improvements.
+
+### Issue 1: Inconsistent Naming
+**Location**: `src/components/UserProfile.jsx`
+**Severity**: 🟢 Low - Standards
+**Category**: Standards - Naming conventions
+
+**Problem**: Mix of camelCase and snake_case for variable names.
+
+**Current**: `user_name`, `userId`, `profile_data`
+**Standard**: All camelCase (per `standards/global/coding-style.md`)
+**Recommended**: `userName`, `userId`, `profileData`
+
+---
+
+## Positive Observations ✅
+
+Things done well that should be maintained:
+
+1. **Excellent error handling** (lines 23-35): Comprehensive try-catch with structured logging
+2. **Good separation of concerns**: Controller → Service → Repository pattern followed
+3. **Clear naming**: Functions and variables have descriptive names
+4. **Type safety**: Good use of TypeScript types (if applicable)
+5. **Documentation**: Complex algorithms are well-commented
+
+---
+
+## Standards Compliance Checklist
+
+Against `.sublation-os/standards/`:
+
+- ✅ **Coding style**: Follows indentation and formatting rules
+- ✅ **Naming conventions**: Mostly consistent (minor issues noted above)
+- ❌ **Error handling**: Missing structured logging in error paths
+- ✅ **API design**: RESTful conventions followed
+- ⚠️ **Testing**: Insufficient test coverage (45% vs 80% requirement)
+- ✅ **Documentation**: Adequate inline comments
+- ✅ **Validation**: Input validation present
+
+---
+
+## Past Learnings Applied
+
+From `.sublation-os/memory/`:
+
+✅ **Applied**: Entry 8 (backend-lessons) - Used repository pattern correctly
+✅ **Applied**: Entry 15 (frontend-lessons) - Followed component composition pattern
+❌ **Missed**: Entry 12 (backend-lessons) - N+1 query antipattern present (flagged above)
+❌ **Missed**: Entry 23 (testing-lessons) - Missing edge case tests
+
+---
+
+## Testing Gaps
+
+**Current coverage**: ~45% (estimated from test files)
+**Required coverage**: 80% (per `standards/testing/test-writing.md`)
+
+**Missing tests**:
+1. Edge case: Empty array input to `processOrders()`
+2. Error case: Network failure in API call
+3. Validation: Invalid email format handling
+4. Performance: Large dataset handling (1000+ items)
+
+**Recommended test additions**:
+```javascript
+// High priority test to add
+describe('processOrders edge cases', () => {
+  it('should handle empty order array', async () => {
+    const result = await processOrders([]);
+    expect(result).toEqual([]);
+  });
+
+  it('should handle API failure gracefully', async () => {
+    mockApi.get.mockRejectedValue(new Error('Network error'));
+    await expect(processOrders(validOrders))
+      .rejects.toThrow('Failed to process orders');
+  });
+});
+```
+
+---
+
+## Architecture Assessment
+
+**Pattern analysis**:
+- ✅ **Layered architecture**: Clear separation (Controller/Service/Repository)
+- ✅ **Dependency injection**: Services injected, testable
+- ⚠️ **Single Responsibility**: Some functions do too much (noted above)
+- ✅ **DRY principle**: Minimal duplication
+- ❌ **Open/Closed**: Some classes hard to extend (tight coupling)
+
+**Recommendations**:
+1. Extract interface for OrderService to enable easier mocking
+2. Consider strategy pattern for different payment processors
+3. Use factory pattern for report generation (currently hardcoded)
+
+---
+
+## Security Assessment
+
+**Vulnerabilities found**: 1 critical (SQL injection), 0 high, 2 medium
+
+**Security checklist**:
+- ❌ **Input validation**: Missing sanitization in userId parameter (CRITICAL)
+- ✅ **Authentication**: JWT properly verified
+- ✅ **Authorization**: Role checks present
+- ⚠️ **Data exposure**: Sensitive fields (password hash) returned in API response
+- ✅ **Dependencies**: No known vulnerabilities (checked npm audit)
+- ✅ **Secrets**: No hardcoded credentials
+- ✅ **HTTPS**: Enforced for all endpoints
+
+---
+
+## Performance Assessment
+
+**Bottlenecks identified**:
+1. 🟠 N+1 query in order loading (~5s response time)
+2. 🟡 Synchronous file operations blocking event loop
+3. 🟡 Large payload (2MB) - no pagination
+
+**Performance recommendations**:
+1. Fix N+1 query (50-100x improvement)
+2. Use async file operations or worker threads
+3. Implement cursor pagination for large datasets
+4. Add caching for frequently accessed data (e.g., user profiles)
+
+**Estimated impact**: Fixing top 2 issues could reduce response time from ~6s to ~200ms.
+
+---
+
+## Refactoring Opportunities
+
+**Technical debt identified**:
+
+1. **Extract utility functions**: Date formatting code repeated 5 times
+2. **Simplify complex conditionals**: Lines 145-180 have deeply nested if statements
+3. **Remove dead code**: Commented-out code at lines 200-220
+4. **Upgrade patterns**: Still using callbacks where async/await would be clearer
+
+**Priority**: Medium (not blocking, but improves maintainability)
+
+---
+
+## Action Items
+
+### Must Do (Before Merge) 🔴
+1. [ ] Fix SQL injection vulnerability (Line 45)
+2. [ ] {Other critical issues}
+
+### Should Do (This Sprint) 🟠
+1. [ ] Fix N+1 query performance issue
+2. [ ] Add missing error handling with structured logging
+3. [ ] Increase test coverage to 80%
+
+### Nice to Have (Backlog) 🟡🟢
+1. [ ] Refactor complex validator function
+2. [ ] Standardize variable naming
+3. [ ] Add caching layer
+4. [ ] Extract repeated utility functions
+
+---
+
+## Recommendations for Developer
+
+**Strengths to maintain**:
+- Good architectural layering
+- Clear naming and documentation
+- Proper use of design patterns
+
+**Areas for improvement**:
+- Security awareness (parameterized queries)
+- Performance optimization (database query patterns)
+- Test coverage (aim for 80%+)
+
+**Learning resources**:
+- SQL injection prevention: [OWASP guide]
+- N+1 queries: See `backend-lessons.md` Entry 12
+- Testing patterns: See `testing-lessons.md`
+
+---
+
+## Next Review
+
+**When to review again**:
+- After critical issues are fixed
+- Before merging to main branch
+- After adding missing tests
+
+**Focus areas for next review**:
+- Verify security fixes
+- Validate performance improvements
+- Check test coverage increase
+
+---
+
+## Appendix: Investigation Notes
+
+{Include any detailed ReAct investigation cycles that were particularly complex or instructive}
+
+### Investigation 1: SQL Injection Analysis
+
+**THOUGHT**: Saw string concatenation in SQL - potential injection
+
+**ACTION**: Checked if input is validated before query
+
+**OBSERVATION**: No validation found - direct concatenation
+
+**THOUGHT**: Need to confirm this is exploitable and find correct pattern
+
+**ACTION**: Checked similar queries in codebase
+
+**OBSERVATION**: All other queries use parameterized approach - this is the outlier
+
+**CONCLUSION**: Confirmed vulnerability, pattern for fix identified
+```
+
+---
+
+## Quality Standards for Reviews
+
+### Excellent Review Characteristics
+
+✅ **Specific**: References exact file paths and line numbers
+✅ **Actionable**: Provides concrete code examples
+✅ **Reasoned**: Explains WHY something is an issue
+✅ **Contextual**: Considers codebase patterns and history
+✅ **Balanced**: Notes positive aspects, not just problems
+✅ **Prioritized**: Clear severity levels
+✅ **Evidence-based**: Uses ReAct to investigate before concluding
+
+### Poor Review Characteristics
+
+❌ **Vague**: "Code quality could be better"
+❌ **Unreasoned**: "This is wrong" without explanation
+❌ **Inconsistent**: Flags patterns that match codebase style
+❌ **Impractical**: Suggests major refactors without considering cost
+❌ **Unbalanced**: Only criticism, no recognition of good work
+
+---
+
+## Post-Review Actions
+
+### Save Review Report
+Save to: `.sublation-os/reviews/[YYYY-MM-DD]-[file-or-feature-name]-review.md`
+
+### Suggest Learning Capture
+If notable issues found, suggest running `/learn` to capture:
+- New antipatterns discovered
+- Security vulnerabilities specific to this codebase
+- Performance patterns to avoid
+- Better approaches identified
+
+### Track Metrics (Optional)
+Consider tracking over time:
+- Average severity of issues found
+- Time to fix issues by severity
+- Recurring issue patterns
+- Test coverage trends
+
+---
+
+## Integration Points
+
+**With `/investigate`**: If review finds bugs, use `/investigate` to diagnose root cause
+
+**With `/learn`**: Capture codebase-specific patterns discovered during review
+
+**With `implementer-v2`**: Review can inform implementation standards
+
+**With `.sublation-os/memory/`**: Check past learnings, add new ones
+
+---
+
+## Summary
+
+This review command provides:
+- **7-dimensional analysis** (Correctness, Security, Performance, Maintainability, Testing, Architecture, Standards)
+- **Chain of Thought reasoning** for systematic evaluation
+- **ReAct investigation** for suspicious patterns
+- **Severity-based prioritization** with specific action items
+- **Integration with codebase knowledge** (standards + memory)
+- **Concrete, actionable recommendations** with code examples
+- **Balanced perspective** (positive + negative observations)
+- **Documentation** for future reference
+
+The goal is not just to find issues, but to **understand context**, **reason through trade-offs**, and **provide practical guidance** that improves code quality while respecting existing patterns and constraints.

package/.claude/commands/sublation-os/review.md

@@ -0,0 +1,12 @@
+---
+description: Review code for correctness, maintainability, and clarity
+---
+
+## 🧠 Summary
+{Brief overview of what the code does}
+
+## ⚠️ Issues Found
+- {List of bugs, anti-patterns, or risks}
+
+## ✅ Suggestions
+- {Recommended refactors or improvements}