@paths.design/caws-cli 10.1.0 → 11.0.0

package/templates/.cursor/rules/13-language-agnostic-standards.mdc

@@ -1,578 +0,0 @@
----
-description: Language-agnostic engineering standards and universal code quality metrics
-globs:
-alwaysApply: true
----
-
-# Language-Agnostic Engineering Standards
-
-## Core Principle
-
-**Engineering standards must apply universally across all programming languages.** Focus on architectural patterns, quality metrics, and maintainability principles that transcend specific language syntax.
-
-## Universal Code Quality Metrics
-
-### Complexity Standards
-
-**Cyclomatic Complexity:**
-
-- **Maximum per function**: 10
-- **Maximum per class/module**: 20
-- **Critical functions**: 5 (auth, billing, data processing)
-
-**Cognitive Complexity:**
-
-- **Maximum per function**: 15
-- **Maximum per class/module**: 30
-- **UI components**: 20 (higher due to rendering logic)
-
-**Nesting Depth:**
-
-- **Maximum nesting levels**: 4
-- **Preferred**: 2-3 levels with guard clauses
-- **Exception**: Complex algorithms with documented justification
-
-### Maintainability Standards
-
-**Function Size:**
-
-- **Maximum lines per function**: 50
-- **Preferred**: 20-30 lines
-- **Exception**: Complex algorithms with documentation
-
-**File Size:**
-
-- **Maximum lines per file**: 1000
-- **Preferred**: 200-500 lines
-- **Exception**: Generated code or data files
-
-**Parameter Count:**
-
-- **Maximum parameters per function**: 5
-- **Preferred**: 2-3 parameters
-- **Exception**: Configuration objects or builder patterns
-
-**Class/Module Size:**
-
-- **Maximum methods per class**: 10
-- **Maximum fields per class**: 15
-- **Preferred**: 5-7 methods, 8-10 fields
-
-## Universal Architectural Patterns
-
-### Dependency Injection
-
-**All languages must support:**
-
-- Constructor injection for dependencies
-- Interface/contract-based design
-- Testable dependency substitution
-- Clear dependency graphs
-
-**Implementation Examples:**
-
-```typescript
-// TypeScript/JavaScript
-class OrderService {
-  constructor(
-    private userRepo: UserRepository,
-    private paymentService: PaymentService,
-    private notificationService: NotificationService
-  ) {}
-}
-```
-
-```rust
-// Rust
-struct OrderService {
-    user_repo: Box<dyn UserRepository>,
-    payment_service: Box<dyn PaymentService>,
-    notification_service: Box<dyn NotificationService>,
-}
-```
-
-```python
-# Python
-class OrderService:
-    def __init__(self, user_repo: UserRepository, payment_service: PaymentService):
-        self.user_repo = user_repo
-        self.payment_service = payment_service
-```
-
-### Error Handling Patterns
-
-**Universal Error Handling Requirements:**
-
-- Explicit error types (no generic exceptions)
-- Error context preservation
-- Graceful degradation capabilities
-- Comprehensive error logging
-
-**Implementation Examples:**
-
-```typescript
-// TypeScript - Result pattern
-type Result<T, E> = { success: true; data: T } | { success: false; error: E };
-
-async function processOrder(order: Order): Promise<Result<OrderResult, OrderError>> {
-  try {
-    const result = await validateOrder(order);
-    return { success: true, data: result };
-  } catch (error) {
-    return { success: false, error: new OrderError(error.message) };
-  }
-}
-```
-
-```rust
-// Rust - Result type
-fn process_order(order: Order) -> Result<OrderResult, OrderError> {
-    let validated = validate_order(&order)?;
-    let result = calculate_total(&validated)?;
-    Ok(result)
-}
-```
-
-```python
-# Python - Custom exceptions
-class OrderError(Exception):
-    def __init__(self, message: str, context: dict = None):
-        super().__init__(message)
-        self.context = context or {}
-
-def process_order(order: Order) -> OrderResult:
-    try:
-        validated = validate_order(order)
-        return calculate_total(validated)
-    except ValidationError as e:
-        raise OrderError(f"Order validation failed: {e}", {"order_id": order.id})
-```
-
-### Configuration Management
-
-**Universal Configuration Standards:**
-
-- Environment-based configuration
-- Type-safe configuration objects
-- Validation of configuration values
-- Secrets management integration
-
-**Implementation Examples:**
-
-```typescript
-// TypeScript
-interface Config {
-  database: {
-    host: string;
-    port: number;
-    ssl: boolean;
-  };
-  api: {
-    timeout: number;
-    retries: number;
-  };
-}
-
-const config: Config = {
-  database: {
-    host: process.env.DB_HOST || 'localhost',
-    port: parseInt(process.env.DB_PORT || '5432'),
-    ssl: process.env.DB_SSL === 'true',
-  },
-  api: {
-    timeout: parseInt(process.env.API_TIMEOUT || '5000'),
-    retries: parseInt(process.env.API_RETRIES || '3'),
-  },
-};
-```
-
-```rust
-// Rust
-#[derive(Debug, Deserialize)]
-struct Config {
-    database: DatabaseConfig,
-    api: ApiConfig,
-}
-
-#[derive(Debug, Deserialize)]
-struct DatabaseConfig {
-    host: String,
-    port: u16,
-    ssl: bool,
-}
-
-impl Config {
-    fn from_env() -> Result<Self, ConfigError> {
-        let host = env::var("DB_HOST").unwrap_or_else(|_| "localhost".to_string());
-        let port = env::var("DB_PORT")
-            .unwrap_or_else(|_| "5432".to_string())
-            .parse()
-            .map_err(|_| ConfigError::InvalidPort)?;
-
-        Ok(Config {
-            database: DatabaseConfig {
-                host,
-                port,
-                ssl: env::var("DB_SSL").unwrap_or_else(|_| "false".to_string()) == "true",
-            },
-            api: ApiConfig::from_env()?,
-        })
-    }
-}
-```
-
-## Universal Testing Standards
-
-### Test Structure Requirements
-
-**All languages must follow:**
-
-- Given-When-Then structure
-- Descriptive test names
-- Independent test execution
-- Proper setup/teardown
-
-**Implementation Examples:**
-
-```typescript
-// TypeScript/JavaScript
-describe('OrderService', () => {
-  describe('when processing a valid order', () => {
-    it('should return order confirmation', async () => {
-      // Given: Valid order data
-      const order = createValidOrder();
-
-      // When: Processing the order
-      const result = await orderService.processOrder(order);
-
-      // Then: Should return confirmation
-      expect(result.success).toBe(true);
-      expect(result.data.orderId).toBeDefined();
-    });
-  });
-});
-```
-
-```rust
-// Rust
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[tokio::test]
-    async fn test_process_valid_order() {
-        // Given: Valid order data
-        let order = create_valid_order();
-
-        // When: Processing the order
-        let result = order_service.process_order(order).await;
-
-        // Then: Should return confirmation
-        assert!(result.is_ok());
-        let order_result = result.unwrap();
-        assert!(order_result.order_id.is_some());
-    }
-}
-```
-
-```python
-# Python
-class TestOrderService:
-    def test_process_valid_order_returns_confirmation(self):
-        # Given: Valid order data
-        order = self.create_valid_order()
-
-        # When: Processing the order
-        result = self.order_service.process_order(order)
-
-        # Then: Should return confirmation
-        assert result.success is True
-        assert result.data.order_id is not None
-```
-
-### Test Data Management
-
-**Universal Requirements:**
-
-- Realistic test data factories
-- Deterministic test execution
-- Proper cleanup procedures
-- Isolated test environments
-
-## Universal Documentation Standards
-
-### API Documentation
-
-**All languages must provide:**
-
-- Function/method signatures with types
-- Parameter descriptions and constraints
-- Return value specifications
-- Error conditions and exceptions
-- Usage examples
-
-**Implementation Examples:**
-
-````typescript
-/**
- * Processes a customer order and returns confirmation details.
- *
- * @param order - The order to process with validated items and payment info
- * @param options - Optional processing options for customization
- * @returns Promise resolving to order confirmation or rejection details
- * @throws ValidationError when order data is invalid
- * @throws PaymentError when payment processing fails
- * @throws InventoryError when items are unavailable
- *
- * @example
- * ```typescript
- * const order = { items: [...], payment: {...} };
- * const result = await processOrder(order);
- * console.log(`Order ${result.orderId} confirmed`);
- * ```
- */
-async function processOrder(order: Order, options?: ProcessingOptions): Promise<OrderResult> {
-  // Implementation
-}
-````
-
-````rust
-/// Processes a customer order and returns confirmation details.
-///
-/// # Arguments
-/// * `order` - The order to process with validated items and payment info
-/// * `options` - Optional processing options for customization
-///
-/// # Returns
-/// Returns `Ok(OrderResult)` with confirmation details on success
-///
-/// # Errors
-/// * `ValidationError` - When order data is invalid
-/// * `PaymentError` - When payment processing fails
-/// * `InventoryError` - When items are unavailable
-///
-/// # Examples
-/// ```rust
-/// let order = Order { items: vec![...], payment: PaymentInfo {...} };
-/// let result = process_order(order).await?;
-/// println!("Order {} confirmed", result.order_id);
-/// ```
-pub async fn process_order(
-    order: Order,
-    options: Option<ProcessingOptions>
-) -> Result<OrderResult, OrderError> {
-    // Implementation
-}
-````
-
-```python
-def process_order(order: Order, options: Optional[ProcessingOptions] = None) -> OrderResult:
-    """Process a customer order and return confirmation details.
-
-    Args:
-        order: The order to process with validated items and payment info
-        options: Optional processing options for customization
-
-    Returns:
-        OrderResult with confirmation details
-
-    Raises:
-        ValidationError: When order data is invalid
-        PaymentError: When payment processing fails
-        InventoryError: When items are unavailable
-
-    Example:
-        >>> order = Order(items=[...], payment=PaymentInfo(...))
-        >>> result = process_order(order)
-        >>> print(f"Order {result.order_id} confirmed")
-    """
-    # Implementation
-```
-
-## Universal Security Standards
-
-### Input Validation
-
-**All languages must implement:**
-
-- Schema-based validation
-- Type checking at boundaries
-- Sanitization of user input
-- Length and format constraints
-
-### Authentication & Authorization
-
-**Universal Requirements:**
-
-- Token-based authentication
-- Role-based access control
-- Session management
-- Audit logging
-
-### Data Protection
-
-**Universal Standards:**
-
-- Encryption at rest and in transit
-- Secure key management
-- Data anonymization capabilities
-- Privacy compliance measures
-
-## Universal Performance Standards
-
-### Response Time SLAs
-
-**Universal Performance Requirements:**
-
-- API endpoints: P95 < 250ms
-- Database queries: P95 < 100ms
-- File operations: P95 < 500ms
-- Complex computations: P95 < 2000ms
-
-### Resource Management
-
-**Universal Resource Standards:**
-
-- Memory usage monitoring
-- CPU utilization limits
-- Connection pool management
-- Garbage collection optimization
-
-## Universal Monitoring Standards
-
-### Logging Requirements
-
-**All applications must provide:**
-
-- Structured logging (JSON format)
-- Log levels (ERROR, WARN, INFO, DEBUG)
-- Request correlation IDs
-- Performance metrics
-
-### Metrics Collection
-
-**Universal Metrics:**
-
-- Request/response times
-- Error rates and types
-- Resource utilization
-- Business KPIs
-
-### Health Checks
-
-**Universal Health Endpoints:**
-
-- Application health status
-- Dependency health checks
-- Resource availability
-- Business logic validation
-
-## CAWS Integration
-
-### Quality Gate Integration
-
-```bash
-# Run complexity analysis
-caws quality-gates --check-complexity
-
-# Check architectural patterns
-caws quality-gates --check-architecture
-
-# Validate universal standards
-caws quality-gates --check-universal-standards
-```
-
-### Metrics Tracking
-
-```bash
-# Metrics are tracked automatically via working state
-```
-
-### Progress Tracking
-
-```bash
-# Verify acceptance criteria for complexity compliance
-caws verify-acs --spec-id <id>
-```
-
-## Enforcement Mechanisms
-
-### Static Analysis Integration
-
-**Universal Static Analysis:**
-
-- Complexity analysis
-- Dependency analysis
-- Security vulnerability scanning
-- Code quality metrics
-
-### CI/CD Integration
-
-**Universal CI/CD Requirements:**
-
-- Automated testing
-- Quality gate enforcement
-- Security scanning
-- Performance regression testing
-
-### CAWS Quality Gates
-
-```yaml
-# In .caws/working-spec.yaml
-quality_gates:
-  complexity:
-    max_cyclomatic: 10
-    max_cognitive: 15
-    max_nesting: 4
-
-  maintainability:
-    max_function_lines: 50
-    max_file_lines: 1000
-    max_parameters: 5
-
-  architecture:
-    dependency_injection: required
-    error_handling: required
-    configuration_management: required
-```
-
-## Quality Metrics Dashboard
-
-### Universal Quality Score
-
-**Calculation Formula:**
-
-```
-Quality Score = (
-  Complexity Score * 0.2 +
-  Test Coverage Score * 0.3 +
-  Security Score * 0.2 +
-  Performance Score * 0.15 +
-  Documentation Score * 0.15
-) * 100
-```
-
-### Trend Analysis
-
-**Track over time:**
-
-- Quality score trends
-- Complexity growth
-- Test coverage changes
-- Security vulnerability rates
-- Performance degradation
-
-### CAWS Integration
-
-```bash
-# Generate quality report
-caws quality-report --include-complexity --include-architecture
-
-# Track quality trends
-caws metrics trends --metric="quality_score" --period="30d"
-
-# Export quality metrics
-caws metrics export --format=json --include-universal-standards
-```
-
-This rule ensures consistent engineering standards across all programming languages while respecting language-specific idioms and capabilities, fully integrated with CAWS quality gates and metrics tracking.

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

@@ -1,148 +0,0 @@
-# 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)
-
-- `00-claims-verification.mdc` - Production readiness claims require rigorous verification
-- `01-working-style.mdc` - Default agent behavior, edit style, and risk limits
-- `02-quality-gates.mdc` - Comprehensive testing standards and verification requirements
-- `03-infrastructure-standards.mdc` - Infrastructure, deployment, and operational standards
-- `03-naming-and-refactor.mdc` - Canonical naming enforcement and refactor strategies
-- `04-documentation-integrity.mdc` - Documentation must match implementation reality
-- `05-production-readiness-checklist.mdc` - Quick reference checklist for production readiness
-- `05-safe-defaults-guards.mdc` - Safe defaults, guard clauses, and early returns
-- `06-typescript-conventions.mdc` - TypeScript/JS conventions and best practices
-- `07-process-ops.mdc` - Process discipline and server management
-- `08-solid-and-architecture.mdc` - SOLID principles and architectural patterns
-- `09-docstrings.mdc` - Language-specific docstring formats, standards, and file headers
-- `10-documentation-quality-standards.mdc` - Engineering-grade documentation standards
-- `11-scope-management-waivers.mdc` - Scope management, change budgets, and emergency waiver procedures
-- `12-implementation-completeness.mdc` - Anti-fake implementation guardrails with sophisticated TODO detection
-- `13-language-agnostic-standards.mdc` - Universal engineering standards (conditional - applies to code files only)
-
-## 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          |
-
-## Comprehensive Coverage Areas
-
-### Core Engineering Standards
-
-- **Production Readiness**: Rigorous verification requirements with evidence-based claims and accountability measures
-- **Testing Standards**: Complete testing pyramid (unit/integration/E2E) with coverage thresholds and quality gates
-- **Infrastructure**: Database, API, security, monitoring, deployment, and operational standards
-- **Documentation**: Engineering-grade content with reality alignment verification and prohibited patterns
-
-### Advanced Quality Controls
-
-- **Scope Management**: Change budget enforcement with emergency waiver procedures and critical fix protocols
-- **Implementation Completeness**: Anti-fake implementation guardrails with sophisticated TODO detection
-- **Language-Agnostic Standards**: Universal patterns across all programming languages with complexity metrics
-- **Duplication Prevention**: Canonical naming enforcement and refactor strategies (merge-then-delete)
-
-### Development Workflow Standards
-
-- **Working Style**: Risk-based edit principles with targeted edit plans for complex changes
-- **Quality Gates**: Execution discipline, commit hygiene, and automated enforcement
-- **Safe Defaults**: Guard clauses, early returns, and defensive programming patterns
-- **Process Operations**: Server management, hung command handling, and development discipline
-
-### Code Quality & Architecture
-
-- **SOLID Principles**: Single responsibility, open-closed, Liskov substitution, interface segregation, dependency inversion
-- **TypeScript Conventions**: Alias imports, const preferences, and type system management
-- **Documentation Standards**: Language-specific docstring formats and comprehensive API documentation
-- **Authorship & Attribution**: File headers, authorship tracking, and contribution standards
-
-### Risk-Based Enforcement
-
-- **Tier 1 (Critical Systems)**: 90%+ coverage, 95%+ branch, 70%+ mutation, manual review required
-- **Tier 2 (Standard Features)**: 80%+ coverage, 90%+ branch, 50%+ mutation, optional review
-- **Tier 3 (Low Risk)**: 70%+ coverage, 80%+ branch, 30%+ mutation, optional review
-
-### Integration with Existing Tooling
-
-- **TODO Analysis**: Sophisticated detection with confidence scoring and context-aware analysis
-- **CAWS Workflow**: Seamless integration with CAWS validation, testing, and quality gates
-- **Automated Detection**: Ripgrep patterns for banned naming, incomplete implementations, and quality violations
-
-## Key Features
-
-### Sophisticated TODO Detection
-
-- **Context-aware analysis** with confidence scoring (0.0-1.0)
-- **Language-specific patterns** for 13+ languages including Rust, Python, JavaScript, TypeScript
-- **Code stub detection** beyond just comments (detects `pass`, `...`, `NotImplementedError`, etc.)
-- **Dependency resolution** for staged files with blocking analysis
-- **Sophisticated exclusion patterns** to prevent false positives
-
-### Risk-Based Quality Gates
-
-- **Tier 1 (Critical)**: Auth, billing, migrations - 90%+ coverage, 70%+ mutation, manual review
-- **Tier 2 (Standard)**: Features, APIs, data writes - 80%+ coverage, 50%+ mutation, optional review
-- **Tier 3 (Low Risk)**: UI, internal tools - 70%+ coverage, 30%+ mutation, optional review
-
-### Emergency Procedures
-
-- **Scope Management**: Change budget enforcement with automatic detection
-- **Waiver System**: Structured procedures for critical fixes outside scope
-- **Critical Fix Protocols**: Emergency override conditions with proper documentation
-
-### Anti-Pattern Prevention
-
-- **Banned Naming**: Prevents `enhanced-*`, `new-*`, `final-*` duplicate patterns
-- **Implementation Completeness**: Detects fake persistence, stub APIs, placeholder business logic
-- **Documentation Reality**: Ensures documented features actually work
-
-## 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 and existing project tooling:
-
-- **Validation**: `caws validate` checks rule compliance and working spec validity
-- **Testing**: Rules guide comprehensive testing requirements with coverage thresholds
-- **Quality Gates**: Automated enforcement of standards with risk-based tiers
-- **Documentation**: Ensures docs match implementation reality with engineering-grade standards
-- **TODO Analysis**: Sophisticated hidden TODO detection with confidence scoring
-- **Scope Management**: Change budget enforcement with emergency waiver procedures
-- **Implementation Completeness**: Anti-fake implementation guardrails with stub detection
-
-## 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.