@paths.design/caws-cli 7.0.2 → 7.0.3

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

@@ -0,0 +1,148 @@
+# 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.

package/dist/templates/.github/copilot/instructions.md

@@ -0,0 +1,311 @@
+# CAWS Integration Instructions for GitHub Copilot
+
+These instructions help Copilot understand and work with CAWS (Coding Agent Workflow System) quality assurance processes.
+
+## Overview
+
+CAWS provides structured quality assurance for AI-assisted development. When working on CAWS-enabled projects, follow these guidelines to maintain quality standards and leverage CAWS tools effectively.
+
+## CAWS Project Detection
+
+**Check if current project uses CAWS:**
+- Look for `.caws/working-spec.yaml` file
+- Check for `caws` commands in package.json scripts
+- Verify CAWS CLI availability: `caws --version`
+
+## Working with CAWS Working Specifications
+
+**Working specs define project requirements and constraints:**
+
+```yaml
+id: PROJ-001
+title: "Feature implementation"
+risk_tier: 2  # 1=Critical, 2=Standard, 3=Low risk
+mode: feature  # feature|refactor|fix|chore
+change_budget:
+  max_files: 25
+  max_loc: 1000
+scope:
+  in: ["src/", "tests/"]
+  out: ["node_modules/", "dist/"]
+```
+
+**Always validate working specs:**
+```bash
+caws validate .caws/working-spec.yaml
+```
+
+## Quality Assurance Workflow
+
+### 1. Pre-Implementation
+```
+# Get CAWS guidance before starting
+caws agent iterate --current-state "About to implement X"
+
+# CAWS will provide:
+# - Implementation suggestions
+# - Quality requirements
+# - Risk considerations
+```
+
+### 2. During Implementation
+```
+# Regular quality checks
+caws agent evaluate --quiet
+
+# Address any issues immediately
+# Create waivers only when justified
+caws waivers create --reason emergency_hotfix --gates coverage_threshold
+```
+
+### 3. Pre-Commit Validation
+```
+# Comprehensive validation before commits
+caws validate
+caws agent evaluate
+
+# Fix any quality gate failures
+```
+
+## CAWS Quality Gates
+
+### Code Quality Gates
+- **Linting**: ESLint, Prettier formatting
+- **Type Checking**: TypeScript strict mode
+- **Security**: Dependency scanning, secret detection
+- **Performance**: Bundle size, runtime budgets
+
+### Testing Gates
+- **Unit Tests**: Individual component testing
+- **Integration Tests**: Component interaction
+- **Contract Tests**: API contract validation
+- **E2E Tests**: Full workflow testing
+- **Mutation Tests**: Test effectiveness validation
+
+### Analysis Gates
+- **Accessibility**: WCAG 2.1 AA compliance
+- **Complexity**: Maintainability metrics
+- **Coverage**: Test coverage thresholds
+
+## Waiver Management
+
+**Create waivers only for justified exceptions:**
+
+```bash
+# Example: Emergency security fix
+caws waivers create \
+  --title "Critical security vulnerability fix" \
+  --reason emergency_hotfix \
+  --gates coverage_threshold,contract_tests \
+  --expires-at "2025-11-01T00:00:00Z" \
+  --approved-by "security-team" \
+  --impact-level critical \
+  --mitigation-plan "Manual testing completed, security review passed"
+```
+
+**Waiver reasons:**
+- `emergency_hotfix` - Critical production issues
+- `legacy_integration` - Third-party compatibility
+- `experimental_feature` - Sandbox/prototype code
+- `performance_critical` - Hot path optimizations
+- `infrastructure_limitation` - Platform constraints
+
+## Scope Management
+
+**Respect CAWS-defined scope boundaries:**
+
+- **In scope**: Files listed in `scope.in` - full quality requirements apply
+- **Out of scope**: Files in `scope.out` - no CAWS restrictions
+- **Scope warnings**: Files outside primary scope but allowed
+
+**Check scope compliance:**
+```bash
+caws validate --scope-check path/to/file.js
+```
+
+## Risk Tier Considerations
+
+### Tier 1 (Critical) - Highest Quality Standards
+- 90%+ test coverage
+- All security scans pass
+- Performance budgets strictly enforced
+- Manual review required
+- Zero waivers allowed for core gates
+
+### Tier 2 (Standard) - Balanced Quality
+- 80%+ test coverage
+- Security scans pass
+- Performance budgets monitored
+- Peer review recommended
+- Limited waivers allowed
+
+### Tier 3 (Low Risk) - Flexible Development
+- 70%+ test coverage
+- Basic security checks
+- Relaxed performance budgets
+- Self-review acceptable
+- Waivers freely allowed
+
+## Common Patterns
+
+### Feature Development
+1. Update working spec with feature requirements
+2. Get CAWS implementation guidance
+3. Implement with regular quality checks
+4. Create comprehensive tests
+5. Validate all quality gates pass
+6. Generate provenance report
+
+### Bug Fixes
+1. Assess risk tier and impact
+2. Create minimal reproduction
+3. Implement fix with tests
+4. Run quality validation
+5. Create waiver if emergency fix
+6. Update working spec if scope changes
+
+### Refactoring
+1. Establish baseline quality metrics
+2. Create refactoring plan
+3. Implement changes incrementally
+4. Maintain test suite passing
+5. Run comprehensive validation
+6. Update documentation
+
+## Error Handling
+
+### Quality Gate Failures
+```
+❌ CAWS validation failed
+✅ Solution: Run caws validate --suggestions
+✅ Fix identified issues
+✅ Re-run validation
+```
+
+### Scope Violations
+```
+❌ File outside CAWS scope
+✅ Solution: Update .caws/working-spec.yaml scope
+✅ Or create waiver if justified
+```
+
+### Waiver Required
+```
+⚠️ High-risk change detected
+✅ Solution: caws waivers create with justification
+✅ Include mitigation plan
+✅ Get appropriate approval
+```
+
+## Best Practices
+
+### Code Quality
+- Follow established patterns and conventions
+- Write comprehensive tests with new code
+- Maintain existing test coverage
+- Address linting issues immediately
+
+### Documentation
+- Update working specs when requirements change
+- Document waiver justifications thoroughly
+- Keep provenance records current
+- Update API documentation for public interfaces
+
+### Collaboration
+- Communicate waiver needs early
+- Share quality gate results with team
+- Review high-risk changes together
+- Maintain collective code ownership
+
+### Performance
+- Monitor performance budgets during development
+- Optimize hot paths identified by CAWS
+- Address performance regressions immediately
+- Include performance tests for critical paths
+
+## Emergency Procedures
+
+### Production Hotfix
+1. Assess severity and business impact
+2. Create emergency waiver immediately
+3. Implement minimal fix with safety measures
+4. Add comprehensive tests post-fix
+5. Schedule follow-up quality improvements
+
+### Security Vulnerability
+1. Create critical waiver with security approval
+2. Implement minimal security fix
+3. Add security tests and monitoring
+4. Conduct security review
+5. Plan comprehensive fix for next release
+
+## Integration with Other Tools
+
+### Git Workflow
+- Pre-commit hooks run fast CAWS checks
+- Pre-push hooks run comprehensive validation
+- Post-commit hooks update provenance
+- Branch protection requires CAWS validation
+
+### CI/CD Pipeline
+- Automated CAWS quality gates
+- Tier-based conditional execution
+- Waiver validation and auditing
+- Provenance report generation
+
+### IDE Integration
+- Real-time quality feedback
+- Scope boundary enforcement
+- Automatic waiver suggestions
+- Quality dashboard visualization
+
+## Troubleshooting
+
+### CAWS CLI Issues
+```bash
+# Check installation
+caws --version
+
+# Update to latest version
+npm install -g @caws/cli@latest
+
+# Check working spec syntax
+caws validate --suggestions
+```
+
+### Quality Gate Failures
+```bash
+# Get detailed feedback
+caws agent evaluate
+
+# Check specific gate
+caws validate --gate linting
+
+# View waiver options
+caws waivers list --expiring-soon
+```
+
+### Performance Issues
+```bash
+# Skip heavy checks for urgent fixes
+caws validate --skip performance,mutation
+
+# Run fast checks only
+caws agent evaluate --quick
+```
+
+## Support
+
+### Getting Help
+- Run `caws --help` for command reference
+- Check `caws validate --suggestions` for specific issues
+- Review working spec documentation
+- Consult team CAWS guidelines
+
+### Common Issues
+- **Working spec invalid**: Fix YAML syntax and required fields
+- **Scope violations**: Update scope or create waiver
+- **Quality gate failures**: Address root cause, don't just waive
+- **Performance regressions**: Optimize or adjust budgets
+
+Remember: CAWS is designed to maintain quality while enabling development velocity. Use waivers judiciously and always prioritize code quality and security.

package/dist/templates/.idea/runConfigurations/CAWS_Evaluate.xml

@@ -0,0 +1,5 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="CAWS: Evaluate Quality" type="NodeJSConfigurationType" factoryName="Node.js" path-to-js-file="$PROJECT_DIR$/packages/caws-cli/dist/index.js" working-dir="$PROJECT_DIR$" application-parameters="agent evaluate .caws/working-spec.yaml">
+    <method v="2" />
+  </configuration>
+</component>

package/dist/templates/.idea/runConfigurations/CAWS_Validate.xml

@@ -0,0 +1,5 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="CAWS: Validate" type="NodeJSConfigurationType" factoryName="Node.js" path-to-js-file="$PROJECT_DIR$/packages/caws-cli/dist/index.js" working-dir="$PROJECT_DIR$" application-parameters="validate .caws/working-spec.yaml">
+    <method v="2" />
+  </configuration>
+</component>

package/dist/templates/.vscode/launch.json

@@ -0,0 +1,56 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Run CAWS Extension",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/caws-vscode-extension"],
+      "outFiles": ["${workspaceFolder}/packages/caws-vscode-extension/out/**/*.js"],
+      "preLaunchTask": "${workspaceFolder}/packages/caws-vscode-extension:watch"
+    },
+    {
+      "name": "Run CAWS Extension (Host Workspace)",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/caws-vscode-extension", "${workspaceFolder}"],
+      "outFiles": ["${workspaceFolder}/packages/caws-vscode-extension/out/**/*.js"],
+      "preLaunchTask": "${workspaceFolder}/packages/caws-vscode-extension:watch"
+    },
+    {
+      "name": "Debug CAWS Extension",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/packages/caws-vscode-extension/out/extension.js",
+      "args": ["--inspect=6009"],
+      "env": {
+        "CAWS_DEBUG": "true"
+      },
+      "preLaunchTask": "${workspaceFolder}/packages/caws-vscode-extension:compile"
+    },
+    {
+      "name": "Debug MCP Server",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/packages/caws-mcp-server/index.js",
+      "args": [],
+      "env": {
+        "NODE_ENV": "development",
+        "CAWS_DEBUG": "true"
+      },
+      "console": "integratedTerminal"
+    },
+    {
+      "name": "Debug CAWS CLI",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/packages/caws-cli/src/index.js",
+      "args": ["validate", ".caws/working-spec.yaml"],
+      "env": {
+        "NODE_ENV": "development",
+        "CAWS_DEBUG": "true"
+      },
+      "console": "integratedTerminal"
+    }
+  ]
+}

package/dist/templates/.vscode/settings.json

@@ -0,0 +1,93 @@
+{
+  // CAWS VS Code Extension Settings
+  "caws.cli.path": "caws",
+  "caws.autoValidate": true,
+  "caws.showQualityStatus": true,
+  "caws.experimentalMode": false,
+
+  // General IDE settings that work well with CAWS
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit",
+    "source.organizeImports": "explicit"
+  },
+
+  // File associations for CAWS files
+  "files.associations": {
+    ".caws/working-spec.yaml": "yaml",
+    ".caws/waivers/*.yaml": "yaml",
+    "apps/tools/caws/*.js": "javascript"
+  },
+
+  // Exclude CAWS-generated files from search and navigation
+  "files.exclude": {
+    ".caws/cache/": true,
+    ".caws/waivers/review-*.md": true
+  },
+
+  // Search excludes for CAWS artifacts
+  "search.exclude": {
+    ".caws/cache/**": true,
+    "packages/*/dist/**": true,
+    "packages/*/node_modules/**": true
+  },
+
+  // CAWS-aware task definitions
+  "tasks": {
+    "version": "2.0.0",
+    "tasks": [
+      {
+        "label": "CAWS: Validate",
+        "type": "shell",
+        "command": "caws",
+        "args": ["validate"],
+        "group": {
+          "kind": "build",
+          "isDefault": true
+        },
+        "presentation": {
+          "echo": true,
+          "reveal": "always",
+          "focus": false,
+          "panel": "shared"
+        },
+        "problemMatcher": []
+      },
+      {
+        "label": "CAWS: Evaluate Quality",
+        "type": "shell",
+        "command": "caws",
+        "args": ["agent", "evaluate", ".caws/working-spec.yaml"],
+        "group": "test",
+        "presentation": {
+          "echo": true,
+          "reveal": "always",
+          "focus": false,
+          "panel": "shared"
+        }
+      },
+      {
+        "label": "CAWS: Create Waiver",
+        "type": "shell",
+        "command": "caws",
+        "args": ["waivers", "create"],
+        "group": "build"
+      }
+    ]
+  },
+
+  // Recommended extensions for CAWS development
+  "recommendations": [
+    "ms-vscode.vscode-json",
+    "redhat.vscode-yaml",
+    "ms-vscode.vscode-typescript-next",
+    "esbenp.prettier-vscode",
+    "dbaeumer.vscode-eslint"
+  ],
+
+  // Workspace-specific settings
+  "yaml.schemas": {
+    "./.caws/schema/working-spec.schema.json": ".caws/working-spec.yaml",
+    "./.caws/schema/waiver.schema.json": ".caws/waivers/*.yaml"
+  }
+}