@paths.design/caws-cli 3.5.0 → 4.1.0

package/templates/.cursor/rules/15-sophisticated-todo-detection.mdc

@@ -0,0 +1,425 @@
+---
+description: Sophisticated TODO detection patterns and hidden implementation analysis
+globs:
+alwaysApply: true
+---
+
+# Sophisticated TODO Detection & Analysis
+
+## Core Principle
+
+**Detect hidden incomplete implementations beyond simple TODO comments.** Use context-aware analysis with confidence scoring to identify stub implementations, temporary solutions, and incomplete business logic.
+
+## Advanced Detection Patterns
+
+### High-Confidence Hidden TODO Patterns
+
+**Incomplete Implementation Patterns:**
+
+```python
+incomplete_implementation_patterns = [
+    r'\bnot\s+yet\s+implemented\b',
+    r'\bmissing\s+implementation\b',
+    r'\bincomplete\s+implementation\b',
+    r'\bpartial\s+implementation\b',
+    r'\bunimplemented\b',
+    r'\bnot\s+done\b',
+    r'\bpending\s+implementation\b',
+    r'\bto\s+be\s+implemented\b',
+    r'\bwill\s+be\s+implemented\b',
+    r'\bcoming\s+soon\b',
+    r'\bwork\s+in\s+progress\b',
+    r'\bwip\b',
+]
+```
+
+**Placeholder Code Patterns:**
+
+```python
+placeholder_code_patterns = [
+    r'\bplaceholder\s+code\b',
+    r'\bplaceholder\s+implementation\b',
+    r'\bstub\s+implementation\b',
+    r'\bdummy\s+implementation\b',
+    r'\bfake\s+implementation\b',
+    r'\bsimplified\s+.*?\s+implementation\b',
+    r'\bfor\s+now\b.*?(just|simply|only)\s+(concatenate|return|use)',
+    r'\btemporary\s+implementation\b',
+    r'\bmock\s+implementation\b',
+    r'\bsample\s+implementation\b',
+]
+```
+
+**Temporary Solution Patterns:**
+
+```python
+temporary_solution_patterns = [
+    r'\btemporary\s+solution\b',
+    r'\btemporary\s+fix\b',
+    r'\bquick\s+fix\b',
+    r'\bworkaround\b',
+    r'\bhack\b.*?(fix|solution)',
+    r'\bband-aid\s+solution\b',
+    r'\bkludge\b',
+    r'\bcrude\s+solution\b',
+    r'\brough\s+implementation\b',
+]
+```
+
+**Hardcoded Value Patterns:**
+
+```python
+hardcoded_value_patterns = [
+    r'\bhardcoded\s+value\b',
+    r'\bmagic\s+number\b',
+    r'\bmagic\s+string\b',
+    r'\bconstant\s+value\b.*?(replace|change|make\s+configurable)',
+    r'\bfixed\s+value\b',
+    r'\bstatic\s+value\b',
+    r'\bhardcoded\s+constant\b',
+]
+```
+
+**Future Improvement Patterns:**
+
+```python
+future_improvement_patterns = [
+    r'\bin\s+production\b.*?(implement|add|fix)',
+    r'\bin\s+a\s+real\s+implementation\b',
+    r'\beventually\b.*?(implement|add|fix)',
+    r'\bshould\s+be\b.*?(implemented|added|fixed)',
+    r'\bwould\s+be\b.*?(implemented|added|fixed)',
+    r'\bmight\s+be\b.*?(implemented|added|fixed)',
+    r'\bcould\s+be\b.*?(implemented|added|fixed)',
+    r'\blater\b.*?(implement|add|fix)',
+    r'\bsomeday\b.*?(implement|add|fix)',
+]
+```
+
+## Language-Specific Code Stub Detection
+
+### JavaScript/TypeScript Patterns
+
+```python
+javascript_stub_patterns = {
+    'function_stub': re.compile(r'^\s*(async\s+)?function\s+\w+\(.*\)\s*{'),
+    'throw_not_impl': re.compile(r"^\s*throw\s+new\s+Error\((\"|')(TODO|Not\s+Implemented|Not\s+Yet\s+Implemented)"),
+    'return_todo': re.compile(r"^\s*return\s+(null|undefined);\s*//\s*(TODO|PLACEHOLDER)"),
+    'console_log_stub': re.compile(r"^\s*console\.log\(.*?\);\s*//\s*(TODO|PLACEHOLDER|STUB)"),
+    'empty_function': re.compile(r'^\s*(async\s+)?function\s+\w+\(.*\)\s*{\s*}\s*$'),
+    'return_mock': re.compile(r"^\s*return\s+\{.*?\};\s*//\s*(MOCK|FAKE|DUMMY)"),
+}
+```
+
+### Python Patterns
+
+```python
+python_stub_patterns = {
+    'function_stub': re.compile(r'^\s*def\s+\w+\(.*\):'),
+    'pass_stmt': re.compile(r'^\s*pass\s*$'),
+    'ellipsis_stmt': re.compile(r'^\s*\.\.\.\s*$'),
+    'raise_not_impl': re.compile(r'^\s*raise\s+NotImplementedError'),
+    'return_none': re.compile(r"^\s*return\s+None\s*#\s*(TODO|PLACEHOLDER)"),
+    'print_stub': re.compile(r"^\s*print\(.*?\)\s*#\s*(TODO|PLACEHOLDER|STUB)"),
+    'empty_function': re.compile(r'^\s*def\s+\w+\(.*\):\s*pass\s*$'),
+}
+```
+
+### Rust Patterns
+
+```python
+rust_stub_patterns = {
+    'function_stub': re.compile(r'^\s*(async\s+)?fn\s+\w+\(.*\)\s*->\s*\w+\s*{'),
+    'todo_macro': re.compile(r'^\s*todo!\(\)'),
+    'unimplemented_macro': re.compile(r'^\s*unimplemented!\(\)'),
+    'panic_stub': re.compile(r"^\s*panic!\(\"TODO\"\)"),
+    'return_default': re.compile(r"^\s*Default::default\(\)\s*//\s*(TODO|PLACEHOLDER)"),
+}
+```
+
+## Context-Aware Analysis
+
+### Confidence Scoring
+
+```python
+def calculate_confidence_score(comment: str, line_num: int, file_path: Path) -> float:
+    score = 0.0
+
+    # Check for documentation indicators (reduce score)
+    if is_documentation_comment(comment):
+        score -= 0.5
+
+    # Check for TODO indicators (increase score)
+    if has_todo_indicators(comment):
+        score += 0.3
+
+    # Check if it's in a generated file (reduce score)
+    if is_generated_file(file_path):
+        score -= 0.4
+
+    # Check for implementation context (increase score)
+    if is_implementation_context(comment):
+        score += 0.2
+
+    # Check for business logic context (increase score)
+    if is_business_logic_context(comment):
+        score += 0.3
+
+    return max(-1.0, min(1.0, score))
+```
+
+### Exclusion Patterns
+
+```python
+exclusion_patterns = [
+    r'\bperformance\s+monitoring\b',
+    r'\bperformance\s+optimization\b',
+    r'\bfallback\s+mechanism\b',
+    r'\bbasic\s+authentication\b',
+    r'\bmock\s+object\b',  # For testing
+    r'\bcurrent\s+implementation\b.*?(uses|provides|supports)',
+    r'\bexample\s+implementation\b',
+    r'\bsample\s+code\b',
+    r'\bdemo\s+implementation\b',
+    r'\btest\s+implementation\b',
+]
+```
+
+## Implementation Detection
+
+### Fake Persistence Detection
+
+```python
+fake_persistence_patterns = [
+    r'private\s+\w+:\s*\w+\[\]\s*=\s*\[\]',  # In-memory arrays
+    r'const\s+\w+\s*=\s*\[\]',  # Empty arrays
+    r'let\s+\w+\s*=\s*\[\]',  # Empty arrays
+    r'mock.*database',
+    r'fake.*persistence',
+    r'in-memory.*storage',
+    r'temporary.*storage',
+]
+```
+
+### Mock API Detection
+
+```python
+mock_api_patterns = [
+    r'return\s+\{.*?\};\s*//\s*(MOCK|FAKE|DUMMY)',
+    r'console\.log.*mock',
+    r'hardcoded.*response',
+    r'static.*response',
+    r'fake.*api',
+    r'mock.*endpoint',
+]
+```
+
+### Stub Business Logic Detection
+
+```python
+stub_business_logic_patterns = [
+    r'return\s+\d+;\s*//\s*(TODO|PLACEHOLDER)',
+    r'return\s+true;\s*//\s*(TODO|PLACEHOLDER)',
+    r'return\s+false;\s*//\s*(TODO|PLACEHOLDER)',
+    r'return\s+null;\s*//\s*(TODO|PLACEHOLDER)',
+    r'throw\s+new\s+Error.*not\s+implemented',
+    r'raise.*NotImplementedError',
+]
+```
+
+## CAWS Integration
+
+### Pre-Commit Analysis
+
+```bash
+# Run sophisticated TODO analysis
+check-hidden-todos() {
+  echo "🔍 Running sophisticated TODO analysis..."
+
+  # Check for high-confidence hidden TODOs
+  local hidden_todos=$(grep -r -E "(not yet implemented|missing implementation|incomplete implementation|partial implementation|unimplemented|not done|pending implementation|to be implemented|will be implemented)" src/ | wc -l)
+  if [ "$hidden_todos" -gt 0 ]; then
+    echo "❌ Found $hidden_todos hidden incomplete implementations"
+    echo "All implementations must be complete"
+    exit 1
+  fi
+
+  # Check for placeholder implementations
+  local placeholders=$(grep -r -E "(placeholder code|placeholder implementation|stub implementation|dummy implementation|fake implementation)" src/ | wc -l)
+  if [ "$placeholders" -gt 0 ]; then
+    echo "❌ Found $placeholders placeholder implementations"
+    echo "Replace with real implementations"
+    exit 1
+  fi
+
+  # Check for temporary solutions
+  local temp_solutions=$(grep -r -E "(temporary solution|temporary fix|quick fix|workaround|hack.*fix)" src/ | wc -l)
+  if [ "$temp_solutions" -gt 0 ]; then
+    echo "❌ Found $temp_solutions temporary solutions"
+    echo "Implement proper solutions"
+    exit 1
+  fi
+
+  echo "✅ No hidden incomplete implementations found"
+}
+```
+
+### CI/CD Integration
+
+```yaml
+# Sophisticated TODO analysis in CI
+- name: Check Hidden TODOs
+  run: |
+    echo "🔍 Running sophisticated hidden TODO analysis..."
+
+    # Check for incomplete implementations
+    incomplete_count=$(grep -r -E "(not yet implemented|missing implementation|incomplete implementation|partial implementation|unimplemented|not done|pending implementation|to be implemented|will be implemented)" src/ | wc -l)
+    if [ "$incomplete_count" -gt 0 ]; then
+      echo "❌ Found $incomplete_count hidden incomplete implementations"
+      echo "All implementations must be complete"
+      exit 1
+    fi
+
+    # Check for placeholder implementations
+    placeholder_count=$(grep -r -E "(placeholder code|placeholder implementation|stub implementation|dummy implementation|fake implementation)" src/ | wc -l)
+    if [ "$placeholder_count" -gt 0 ]; then
+      echo "❌ Found $placeholder_count placeholder implementations"
+      echo "Replace with real implementations"
+      exit 1
+    fi
+
+    # Check for temporary solutions
+    temp_count=$(grep -r -E "(temporary solution|temporary fix|quick fix|workaround|hack.*fix)" src/ | wc -l)
+    if [ "$temp_count" -gt 0 ]; then
+      echo "❌ Found $temp_count temporary solutions"
+      echo "Implement proper solutions"
+      exit 1
+    fi
+
+    # Check for fake persistence
+    fake_persistence_count=$(grep -r -E "(private.*\[\]|mock.*database|fake.*persistence|in-memory.*storage)" src/ | wc -l)
+    if [ "$fake_persistence_count" -gt 0 ]; then
+      echo "❌ Found $fake_persistence_count fake persistence patterns"
+      echo "Use real database connections"
+      exit 1
+    fi
+
+    echo "✅ No hidden incomplete implementations found"
+
+- name: Generate TODO Analysis Report
+  run: |
+    echo "📊 Generating comprehensive TODO analysis report..."
+
+    # Generate detailed report
+    echo "# Hidden TODO Analysis Report" > hidden-todos-report.md
+    echo "" >> hidden-todos-report.md
+    echo "## Incomplete Implementations" >> hidden-todos-report.md
+    grep -r -E "(not yet implemented|missing implementation|incomplete implementation|partial implementation|unimplemented|not done|pending implementation|to be implemented|will be implemented)" src/ >> hidden-todos-report.md || echo "None found" >> hidden-todos-report.md
+    echo "" >> hidden-todos-report.md
+    echo "## Placeholder Implementations" >> hidden-todos-report.md
+    grep -r -E "(placeholder code|placeholder implementation|stub implementation|dummy implementation|fake implementation)" src/ >> hidden-todos-report.md || echo "None found" >> hidden-todos-report.md
+    echo "" >> hidden-todos-report.md
+    echo "## Temporary Solutions" >> hidden-todos-report.md
+    grep -r -E "(temporary solution|temporary fix|quick fix|workaround|hack.*fix)" src/ >> hidden-todos-report.md || echo "None found" >> hidden-todos-report.md
+    echo "" >> hidden-todos-report.md
+    echo "## Fake Persistence Patterns" >> hidden-todos-report.md
+    grep -r -E "(private.*\[\]|mock.*database|fake.*persistence|in-memory.*storage)" src/ >> hidden-todos-report.md || echo "None found" >> hidden-todos-report.md
+
+    echo "📊 TODO analysis report generated"
+```
+
+## CAWS Commands
+
+### TODO Analysis Commands
+
+```bash
+# Run comprehensive TODO analysis
+caws analyze-todos --confidence-threshold=0.7
+
+# Check for hidden incomplete implementations
+caws analyze-todos --pattern="incomplete_implementation" --confidence-threshold=0.8
+
+# Analyze placeholder implementations
+caws analyze-todos --pattern="placeholder_code" --confidence-threshold=0.6
+
+# Check for temporary solutions
+caws analyze-todos --pattern="temporary_solution" --confidence-threshold=0.7
+
+# Analyze fake persistence patterns
+caws analyze-todos --pattern="fake_persistence" --confidence-threshold=0.8
+```
+
+### Quality Monitoring
+
+```bash
+# Track TODO resolution progress
+caws quality-monitor --action=code_edited --files="$(git diff --name-only)" --check-hidden-todos
+
+# Update progress with TODO resolution
+caws progress update --criterion-id="TODO-001" --status="completed" --tests-passing=1
+
+# Track implementation completeness metrics
+caws metrics track --metric="hidden_todos_count" --value=0
+caws metrics track --metric="placeholder_implementations" --value=0
+caws metrics track --metric="temporary_solutions" --value=0
+```
+
+## Quality Metrics
+
+### Implementation Completeness Score
+
+```python
+def calculate_completeness_score(analysis_results):
+    total_files = analysis_results['total_files']
+    files_with_todos = analysis_results['files_with_hidden_todos']
+    high_conf_todos = analysis_results['high_confidence_todos']
+
+    # Completeness score (higher is better)
+    completeness_score = 1.0 - (files_with_todos / total_files) if total_files > 0 else 1.0
+
+    # Quality score based on confidence levels
+    quality_score = 1.0 - (high_conf_todos / total_files) if total_files > 0 else 1.0
+
+    return {
+        'completeness_score': completeness_score,
+        'quality_score': quality_score,
+        'files_with_todos': files_with_todos,
+        'high_confidence_todos': high_conf_todos,
+        'total_files_analyzed': total_files
+    }
+```
+
+### Anti-Pattern Detection Metrics
+
+- **Placeholder Density**: Number of high-confidence TODOs per 1000 lines
+- **Stub Implementation Rate**: % of functions with stub patterns detected
+- **Temporary Solution Rate**: % of code marked as temporary/workaround
+- **Hardcoded Value Rate**: % of magic numbers/strings detected
+- **Fake Persistence Rate**: % of code using in-memory storage patterns
+
+## Continuous Improvement
+
+### Monthly Audits
+
+```bash
+# Generate monthly completeness report
+grep -r -E "(not yet implemented|missing implementation|incomplete implementation|partial implementation|unimplemented|not done|pending implementation|to be implemented|will be implemented)" src/ > monthly-hidden-todos.txt
+grep -r -E "(placeholder code|placeholder implementation|stub implementation|dummy implementation|fake implementation)" src/ > monthly-placeholders.txt
+grep -r -E "(temporary solution|temporary fix|quick fix|workaround|hack.*fix)" src/ > monthly-temp-solutions.txt
+
+# Track trends over time
+echo "Implementation completeness trends:" >> monthly-report.md
+echo "- Hidden incomplete implementations: $(wc -l < monthly-hidden-todos.txt)" >> monthly-report.md
+echo "- Placeholder implementations: $(wc -l < monthly-placeholders.txt)" >> monthly-report.md
+echo "- Temporary solutions: $(wc -l < monthly-temp-solutions.txt)" >> monthly-report.md
+```
+
+### Quarterly Reviews
+
+- Full implementation audit across entire codebase
+- Review integration reality and persistence patterns
+- Update quality gates based on project evolution
+- Refine detection patterns based on new anti-patterns
+- Analyze confidence threshold effectiveness
+
+This rule ensures sophisticated detection of hidden incomplete implementations beyond simple TODO comments, providing context-aware analysis with confidence scoring to maintain high code quality standards.

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

@@ -0,0 +1,150 @@
+# 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 and standards
+- `10-authorship-and-attribution.mdc` - File headers and authorship standards
+- `16-documentation-quality-standards.mdc` - Engineering-grade documentation standards
+- `17-scope-management-waivers.mdc` - Scope management, change budgets, and emergency waiver procedures
+- `18-implementation-completeness.mdc` - Anti-fake implementation guardrails and completeness verification
+- `19-language-agnostic-standards.mdc` - Universal engineering standards across all programming languages
+- `20-sophisticated-todo-detection.mdc` - Advanced TODO detection patterns and hidden implementation analysis
+
+## 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.