@paths.design/caws-cli 4.0.0 → 5.0.0

package/templates/.cursor/rules/04-documentation-integrity.mdc

@@ -1,291 +0,0 @@
----
-description: Documentation must match implementation reality - no claims of unimplemented features
-globs:
-alwaysApply: true
----
-
-# Documentation Integrity & Reality Alignment
-
-## Core Principle
-
-**Documentation must accurately reflect implementation reality.** Never claim features exist that don't work, APIs that aren't implemented, or capabilities that are just placeholders.
-
-## Documentation Standards
-
-### README Accuracy
-
-- **Feature Claims**: Only document features that are fully implemented and tested
-- **Installation Instructions**: Must work on a clean environment
-- **Usage Examples**: Code examples must run without errors
-- **API Documentation**: All documented endpoints must exist and work
-- **Prerequisites**: All required dependencies and versions listed
-
-### API Documentation
-
-- **Endpoint Completeness**: All documented endpoints implemented
-- **Parameter Accuracy**: Request/response schemas match implementation
-- **Error Responses**: Documented error codes match actual errors
-- **Authentication**: Auth requirements match implementation
-- **Examples**: Working code examples for all major endpoints
-
-### Architecture Documentation
-
-- **Component Diagrams**: Reflect actual code structure
-- **Data Flow**: Match actual data processing paths
-- **Integration Points**: Document real integrations, not planned ones
-- **Deployment Architecture**: Match actual infrastructure
-- **Scaling Strategy**: Based on implemented capabilities
-
-## Implementation vs Documentation Verification
-
-### Feature Claims Verification
-
-Before documenting any feature, verify:
-
-- [ ] Feature fully implemented (not placeholder/mock)
-- [ ] Feature tested end-to-end
-- [ ] Feature handles error cases
-- [ ] Feature documented in user-facing docs
-- [ ] Feature matches acceptance criteria
-
-### API Documentation Verification
-
-For every documented API:
-
-- [ ] Endpoint exists and responds
-- [ ] Request/response formats match docs
-- [ ] Authentication works as documented
-- [ ] Error handling matches documentation
-- [ ] Rate limits implemented if documented
-
-### Code Documentation Verification
-
-For all public APIs:
-
-- [ ] JSDoc/TSDoc comments accurate
-- [ ] Parameter types match implementation
-- [ ] Return types correct
-- [ ] Error conditions documented
-- [ ] Usage examples work
-
-## Prohibited Documentation Patterns
-
-### ❌ Feature Bloat Documentation
-
-```markdown
-<!-- DON'T document unimplemented features -->
-
-## Features
-
-- ✅ User authentication
-- ✅ Real-time notifications
-- ✅ Advanced analytics dashboard <!-- Not implemented yet -->
-- ✅ Machine learning recommendations <!-- Placeholder only -->
-```
-
-### ❌ Vague Status Claims
-
-```markdown
-<!-- DON'T use ambiguous status -->
-
-Status: Production Ready (75% complete) <!-- Confusing -->
-Status: In Development (25% complete) <!-- Better -->
-```
-
-### ❌ Outdated Examples
-
-```javascript
-// DON'T: Example that doesn't work
-fetch("/api/users", {
-  method: "POST",
-  body: JSON.stringify({ name: "John" }), // Missing required email field
-});
-```
-
-### ❌ Missing Error Documentation
-
-```typescript
-// DON'T: Undocumented error conditions
-function processPayment(amount: number): Promise<PaymentResult> {
-  // What happens if amount < 0? Not documented
-}
-```
-
-## Documentation Maintenance Standards
-
-### Change Documentation Updates
-
-- **Breaking Changes**: Update documentation immediately
-- **New Features**: Document before release
-- **API Changes**: Update API docs in same PR
-- **Deprecations**: Mark deprecated features clearly
-- **Migration Guides**: Provide for breaking changes
-
-### Version Consistency
-
-- **Changelog**: Accurate for each version
-- **Version Numbers**: Match actual releases
-- **Deprecation Notices**: Clear timelines and alternatives
-- **Compatibility Matrix**: Accurate version compatibility
-
-### Documentation Testing
-
-- **Link Validation**: All links in docs work
-- **Code Example Testing**: Examples tested in CI
-- **Installation Verification**: Setup instructions tested
-- **Cross-Platform**: Docs work on documented platforms
-
-## Reality Alignment Checks
-
-### Implementation Inventory
-
-Maintain accurate inventory:
-
-- [ ] Count actual source files vs documented components
-- [ ] Verify test coverage matches claims
-- [ ] Check database schema matches docs
-- [ ] Validate configuration options exist
-- [ ] Confirm external integrations work
-
-### Feature Parity Audit
-
-Regular audits to ensure:
-
-- [ ] No documented features are missing
-- [ ] No implemented features are undocumented
-- [ ] No placeholder implementations documented as complete
-- [ ] No deprecated features still documented as current
-
-### User Experience Verification
-
-- [ ] Onboarding works as documented
-- [ ] Common use cases work end-to-end
-- [ ] Error messages helpful and accurate
-- [ ] Performance matches documented SLAs
-
-## Correct Documentation Patterns
-
-### ✅ Accurate Feature Status
-
-```markdown
-## Features
-
-### ✅ Implemented
-
-- User authentication with JWT tokens
-- Real-time notifications via WebSocket
-- Basic analytics dashboard
-
-### 🚧 In Development
-
-- Advanced ML recommendations (Q2 2025)
-- Multi-tenant isolation (Q1 2025)
-
-### 📋 Planned
-
-- AI-powered chat support (Q3 2025)
-```
-
-### ✅ Working Code Examples
-
-```javascript
-// POST /api/users
-const response = await fetch("/api/users", {
-  method: "POST",
-  headers: {
-    "Content-Type": "application/json",
-    Authorization: `Bearer ${token}`,
-  },
-  body: JSON.stringify({
-    name: "John Doe",
-    email: "john@example.com", // Required field included
-    password: "securePassword123",
-  }),
-});
-
-if (!response.ok) {
-  throw new Error(`Failed to create user: ${response.statusText}`);
-}
-
-const user = await response.json();
-console.log("Created user:", user);
-```
-
-### ✅ Complete API Documentation
-
-```typescript
-/**
- * Creates a new user account
- * @param userData User registration data
- * @returns Promise<User> The created user object
- * @throws ValidationError if email format invalid
- * @throws ConflictError if email already exists
- * @throws RateLimitError if too many requests
- */
-async function createUser(userData: CreateUserRequest): Promise<User> {
-  // Implementation
-}
-```
-
-### ✅ Realistic Status Claims
-
-```markdown
-# Project Status
-
-**Current Status**: In Development (Proof of Concept)
-
-**Production Readiness**: 25% - Core authentication and basic API working, but missing:
-
-- Database persistence (in-memory only)
-- Security hardening
-- Comprehensive testing
-- Production deployment pipeline
-
-**Next Milestone**: Alpha release (Q1 2025) with full persistence layer
-```
-
-## Documentation Quality Metrics
-
-### Completeness Score
-
-- **API Coverage**: % of public APIs documented
-- **Feature Documentation**: % of features with user docs
-- **Code Examples**: % of APIs with working examples
-- **Error Documentation**: % of error conditions documented
-
-### Accuracy Score
-
-- **Working Examples**: % of code examples that run successfully
-- **Link Validity**: % of documentation links that work
-- **Version Accuracy**: % of version references that are current
-- **Implementation Match**: % of documented features that work as described
-
-### Maintenance Score
-
-- **Update Frequency**: How often docs are updated vs code changes
-- **Review Coverage**: % of doc changes that are reviewed
-- **User Feedback**: Response time to documentation issues
-- **Cross-Platform**: % of supported platforms with verified docs
-
-## Enforcement Mechanisms
-
-### Automated Checks
-
-- **Documentation Tests**: CI runs documentation validation
-- **Link Checking**: Automated link validation in docs
-- **Example Testing**: Code examples executed in CI
-- **API Contract Testing**: Docs vs implementation validation
-
-### Review Requirements
-
-- **Documentation Reviews**: Require review for doc changes
-- **Implementation Reviews**: Check docs match implementation
-- **User Testing**: Validate docs from user perspective
-- **Cross-Functional Reviews**: Include different roles in reviews
-
-### Accountability Measures
-
-- **Documentation Debt**: Track unimplemented documented features
-- **Reality Gap Metrics**: Measure docs vs implementation accuracy
-- **User Feedback Integration**: Incorporate user-reported doc issues
-- **Continuous Improvement**: Regular documentation quality reviews

package/templates/.cursor/rules/05-production-readiness-checklist.mdc

@@ -1,214 +0,0 @@
----
-description: Quick reference checklist for production readiness verification
-globs:
-alwaysApply: true
----
-
-# Production Readiness Verification Checklist
-
-**Before claiming "production-ready", "production-grade", or similar, complete this entire checklist.**
-
-## 🔍 Pre-Claim Verification Process
-
-### □ Code Quality Gates
-
-- [ ] `npm run lint` shows **zero errors** (ESLint, TypeScript, etc.)
-- [ ] `npm run typecheck` passes with **zero TypeScript errors**
-- [ ] No TODOs, PLACEHOLDERs, or MOCK DATA in production code (`src/`)
-- [ ] No unused imports or dead code
-- [ ] Code formatting consistent (Prettier/ESLint rules)
-
-### □ Testing & Quality Assurance
-
-- [ ] `npm test` passes **all tests** (unit, integration, e2e)
-- [ ] **No tests skipped** in production code
-- [ ] Coverage meets thresholds: 80%+ lines, 90%+ branches
-- [ ] Database integration tests use **real database** (not mocked)
-- [ ] All external API integrations tested with real endpoints
-- [ ] Mutation testing scores: 70%+ for critical components
-- [ ] Performance tests meet documented SLAs
-
-### □ Infrastructure & Persistence
-
-- [ ] **Real database persistence** implemented (not in-memory mocks)
-- [ ] Database integration tests pass with real PostgreSQL/MySQL/etc.
-- [ ] Migration scripts tested and working
-- [ ] Data consistency and transaction handling verified
-- [ ] Connection pooling configured and tested
-- [ ] Backup and recovery procedures documented and tested
-
-### □ Security & Reliability
-
-- [ ] Security controls tested and validated (auth, authorization, input validation)
-- [ ] **Zero security scan violations** (SAST, dependency scans)
-- [ ] Circuit breakers implemented for external dependencies
-- [ ] Graceful degradation tested under failure conditions
-- [ ] Comprehensive logging and monitoring implemented
-- [ ] Rate limiting and DDoS protection configured
-
-### □ Documentation & Reality Alignment
-
-- [ ] **Documentation matches implementation reality** (no claims of missing features)
-- [ ] README installation instructions work on clean environment
-- [ ] API documentation current and all endpoints functional
-- [ ] Code examples in docs run without errors
-- [ ] Architecture diagrams reflect actual code structure
-- [ ] Changelog accurate and version numbers correct
-
-### □ Deployment & Operations
-
-- [ ] CI/CD pipeline passes all stages
-- [ ] Deployment automation tested and working
-- [ ] Rollback procedures documented and tested
-- [ ] Environment configuration validated
-- [ ] Health checks implemented and working
-- [ ] Monitoring and alerting configured
-
-### □ Scalability & Performance
-
-- [ ] Load testing completed with realistic user counts
-- [ ] Response times meet documented SLAs (P95 < defined limits)
-- [ ] Memory usage within acceptable bounds
-- [ ] Database query performance optimized
-- [ ] Caching strategy implemented and tested
-- [ ] Horizontal scaling capability verified
-
-## 🚫 If ANY Item Is Unchecked
-
-**DO NOT claim production readiness.** Instead use:
-
-- ❌ **"In development"** - Active development with known issues
-- ❌ **"Partially implemented"** - Some features working, major gaps remain
-- ❌ **"Proof of concept"** - Core concept demonstrated, not production-viable
-- ❌ **"Beta/Alpha release"** - Limited production use with close monitoring
-
-## 📊 Evidence Requirements
-
-When claiming production readiness, provide:
-
-- [ ] Test execution results (screenshots/logs)
-- [ ] Coverage reports showing adequate thresholds
-- [ ] Lint results showing zero errors
-- [ ] Security scan reports with zero violations
-- [ ] Performance benchmark results
-- [ ] Database connectivity and migration proofs
-- [ ] CI/CD pipeline success evidence
-- [ ] Deployment verification logs
-- [ ] User acceptance testing results
-
-## 🏆 Production-Grade Status Requirements
-
-### Enterprise Production (Tier 1)
-
-- [ ] 99.9%+ uptime SLA
-- [ ] <1 second P95 API response times
-- [ ] 95%+ test coverage across all components
-- [ ] Zero critical security vulnerabilities
-- [ ] Automated deployment and rollback
-- [ ] 24/7 monitoring and incident response
-- [ ] Multi-region deployment capability
-- [ ] Comprehensive audit logging
-
-### Standard Production (Tier 2)
-
-- [ ] 99.5%+ uptime SLA
-- [ ] <3 second P95 API response times
-- [ ] 85%+ test coverage
-- [ ] No high-risk security vulnerabilities
-- [ ] Semi-automated deployment process
-- [ ] Business hours monitoring
-- [ ] Single-region deployment
-- [ ] Basic audit logging
-
-### Minimum Viable Production (Tier 3)
-
-- [ ] 99%+ uptime SLA
-- [ ] <10 second P95 API response times
-- [ ] 70%+ test coverage
-- [ ] No critical security vulnerabilities
-- [ ] Manual deployment process
-- [ ] Basic monitoring
-- [ ] Single environment
-- [ ] Error logging only
-
-## 🔄 Continuous Verification
-
-### Daily/Weekly Checks
-
-- [ ] All tests still passing
-- [ ] No new linting errors
-- [ ] Security scans clean
-- [ ] Performance within SLAs
-- [ ] No breaking changes without documentation updates
-
-### Monthly Reviews
-
-- [ ] Dependency updates applied
-- [ ] Security patches deployed
-- [ ] Performance optimizations reviewed
-- [ ] Documentation accuracy verified
-- [ ] Backup/recovery procedures tested
-
-### Quarterly Audits
-
-- [ ] Full security assessment
-- [ ] Penetration testing completed
-- [ ] Load testing under increased capacity
-- [ ] Disaster recovery simulation
-- [ ] Compliance requirements verified
-
-## ⚠️ Warning Signs of Unready Code
-
-### Red Flags (Immediate Rejection)
-
-- TODO comments in core business logic
-- Console.log statements in production code
-- Hardcoded configuration values
-- Missing error handling in critical paths
-- Database operations without transactions
-- API endpoints without authentication
-- Tests that mock the system under test
-- Documentation claiming 100% coverage with failing tests
-
-### Yellow Flags (Requires Investigation)
-
-- Complex functions > 50 lines
-- Classes with > 10 methods
-- Files > 500 lines
-- Test files with low coverage
-- Dependencies without security audits
-- Manual deployment processes
-- Limited monitoring capabilities
-
-### Green Flags (Positive Indicators)
-
-- Comprehensive error handling
-- Transaction-wrapped database operations
-- Input validation and sanitization
-- Automated testing and deployment
-- Security headers and controls
-- Performance monitoring and alerting
-- Clear separation of concerns
-- Well-documented APIs and contracts
-
-## 📋 Quick Assessment Matrix
-
-| Category       | Question                                   | Points   | Max    |
-| -------------- | ------------------------------------------ | -------- | ------ |
-| Code Quality   | Zero linting errors?                       | 0-10     | 10     |
-| Testing        | All tests pass + coverage >80%?            | 0-15     | 15     |
-| Security       | Security scans pass + controls tested?     | 0-15     | 15     |
-| Infrastructure | Real database + migrations + monitoring?   | 0-15     | 15     |
-| Documentation  | Matches implementation + working examples? | 0-10     | 10     |
-| Deployment     | Automated CI/CD + rollback capability?     | 0-10     | 10     |
-| Performance    | Meets SLAs + load tested?                  | 0-10     | 10     |
-| **TOTAL**      |                                            | **0-85** | **85** |
-
-### Scoring Guide
-
-- **70-85 points**: Production-ready (Tier 1)
-- **50-69 points**: Production-viable (Tier 2)
-- **30-49 points**: Minimum viable production (Tier 3)
-- **0-29 points**: Not production-ready
-
-**Only claim production readiness if scoring 50+ points with all critical categories (Testing, Security, Infrastructure) at 80%+.**