@paths.design/caws-cli 3.4.0 → 4.0.0

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

@@ -0,0 +1,291 @@
+---
+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

@@ -0,0 +1,214 @@
+---
+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%+.**

package/templates/.cursor/rules/README.md

@@ -0,0 +1,64 @@
+# Cursor Rules for CAWS Projects
+
+This directory contains modular rule files that Cursor uses to guide development in CAWS projects.
+
+## Rule Files
+
+### Always Applied (Core Governance)
+
+- `01-claims-verification.mdc` - Production readiness claims require verification
+- `02-testing-standards.mdc` - Comprehensive testing standards and verification
+- `03-infrastructure-standards.mdc` - Infrastructure, deployment, and operational standards
+- `04-documentation-integrity.mdc` - Documentation must match implementation reality
+- `05-production-readiness-checklist.mdc` - Quick reference checklist for production readiness
+
+## How MDC Works
+
+Each `.mdc` file has frontmatter that controls when it applies:
+
+```yaml
+---
+description: Brief description of the rule
+globs:
+alwaysApply: true
+---
+```
+
+- **alwaysApply: true** - Rule is always active
+- **globs: [...]** - Rule auto-attaches when editing matching files
+
+## CAWS Quality Standards
+
+These rules enforce CAWS quality tiers:
+
+| Tier      | Coverage | Mutation | Use Case                    |
+| --------- | -------- | -------- | --------------------------- |
+| 🔴 **T1** | 90%+     | 70%+     | Auth, billing, migrations   |
+| 🟡 **T2** | 80%+     | 50%+     | Features, APIs, data writes |
+| 🟢 **T3** | 70%+     | 30%+     | UI, internal tools          |
+
+## Usage
+
+Cursor automatically loads these rules from `.cursor/rules/`. View active rules in Cursor's sidebar.
+
+To disable a rule temporarily: Cursor Settings → Rules → Toggle specific rule
+
+## Integration with CAWS Workflow
+
+These rules complement CAWS tools:
+
+- **Validation**: `caws validate` checks rule compliance
+- **Testing**: Rules guide comprehensive testing requirements
+- **Quality Gates**: Automated enforcement of standards
+- **Documentation**: Ensures docs match implementation reality
+
+## Continuous Improvement
+
+Rules are regularly updated based on:
+
+- Industry best practices
+- CAWS user feedback
+- Production incident analysis
+- Security research and compliance updates
+
+For questions about these rules, see the main CAWS documentation or contact the CAWS team.

package/templates/agents.md

@@ -776,11 +776,11 @@ Real-time quality enforcement:
 ### Disabling Temporarily
 
 ```bash
-# If you need to bypass hooks temporarily
-# Cursor Settings → Hooks → Disable
+# If you need to bypass commit hooks temporarily
+git commit --no-verify  # Allowed for commits
 
-# Note: --no-verify is BANNED for git commits
-# Fix the issue instead of bypassing hooks
+# Note: --no-verify is BLOCKED for git push
+# Push operations must pass all quality gates
 ```
 
 ---
@@ -972,11 +972,12 @@ Only increase budget with human approval and strong justification.
 
 ### Q: What if lints fail but I think they're wrong?
 
-**A: Fix the lints.** Never use `--no-verify`. If the lint rule is incorrect:
+**A: Fix the lints.** You can use `git commit --no-verify` to commit temporarily, but you cannot push without fixing. If the lint rule is incorrect:
 
 1. Fix the code to satisfy the lint
 2. Or request human discussion of the lint rule
 3. Human can update lint config if appropriate
+4. Note: `git push --no-verify` is BLOCKED
 
 ### Q: Can I commit without updating provenance?