@paths.design/caws-cli 7.0.2 → 7.0.3

package/dist/templates/.cursor/rules/00-claims-verification.mdc

@@ -0,0 +1,144 @@
+---
+description: Production readiness claims require rigorous verification - agents must prove, not assert
+globs:
+alwaysApply: true
+---
+
+# Production Readiness Verification & Accountability
+
+## Core Principle
+
+**Never claim "production-ready", "production-grade", or similar unless ALL criteria below are met.** If any criterion is not satisfied, use these statuses instead:
+
+- ❌ **"In development"** - Active development with known issues
+- ❌ **"Partially implemented"** - Some features working, major gaps remain
+- ❌ **"Proof of concept"** - Core concept demonstrated, not production-viable
+
+## Mandatory Production Readiness Criteria
+
+Before claiming production readiness, **agents must verify ALL of these**:
+
+### ✅ Code Quality Gates
+
+- **Zero linting errors or warnings** (ESLint, TypeScript, etc.)
+- **Zero TypeScript compilation errors**
+- **All TODOs, PLACEHOLDERs, and MOCK DATA cleared from production code**
+- **No dead code or unused imports**
+- **Consistent code formatting** (Prettier/ESLint rules)
+
+### ✅ Testing & Quality Assurance
+
+- **Complete unit test coverage** (80%+ line coverage, 90%+ branch coverage)
+- **All unit tests passing** (no skipped tests in production code)
+- **Integration tests passing** (database, external APIs, end-to-end flows)
+- **Mutation testing** (70%+ score for critical components)
+- **Performance tests** meeting documented SLAs
+
+### ✅ Infrastructure & Persistence
+
+- **Actual database persistence implemented** (not just in-memory mocks)
+- **Database integration tests passing** with real database
+- **Migration scripts tested and working**
+- **Data consistency and rollback capabilities**
+- **Connection pooling and error handling**
+
+### ✅ Security & Reliability
+
+- **Security controls tested and validated** (authentication, authorization, input validation)
+- **No security scan violations** (SAST, dependency scanning)
+- **Circuit breakers and retry logic** for external dependencies
+- **Graceful degradation** under failure conditions
+- **Logging and monitoring** implemented
+
+### ✅ Documentation & Reality Alignment
+
+- **Documentation matches implementation reality** (no claims of features that don't exist)
+- **API documentation** current and accurate
+- **Deployment and operational docs** exist
+- **Architecture diagrams** reflect actual implementation
+- **README and changelogs** accurate
+
+## Accountability Measures for Coding Agents
+
+### Pre-Claim Verification Process
+
+1. **Run full test suite** - All tests pass locally
+2. **Run linters** - Zero errors/warnings
+3. **Run security scans** - No vulnerabilities
+4. **Check coverage reports** - Meet or exceed thresholds
+5. **Verify database operations** - Real persistence working
+6. **Test deployment pipeline** - CI/CD passes
+7. **Document verification evidence** - Include in PR/commit
+
+### Prohibited Claims
+
+**NEVER claim these without verification:**
+
+- "Production-ready" without all criteria met
+- "Enterprise-grade" without enterprise testing
+- "Battle-tested" without comprehensive testing
+- "Stable" with failing tests or linting errors
+- "Complete" with TODOs, placeholders, or mock data
+- "Secure" without security testing and scans
+
+### Evidence Requirements
+
+For any production readiness claim, provide:
+
+- Test execution results (screenshots/logs)
+- Coverage reports
+- Lint results
+- Security scan reports
+- Performance benchmarks
+- Database connectivity proofs
+- Deployment verification
+
+## Common Failure Patterns to Avoid
+
+### Implementation Gaps
+
+- Empty directories claiming "full implementation"
+- Mock functions in production code
+- TODO comments in core business logic
+- Placeholder implementations
+- Missing error handling
+
+### Testing Shortcuts
+
+- Skipping integration tests
+- Mocking database operations
+- Ignoring linting errors
+- Not testing error conditions
+- Fake test data instead of real fixtures
+
+### Documentation Lies
+
+- Claiming 100% coverage with 75% actual
+- Features documented but not implemented
+- APIs documented with wrong signatures
+- Missing breaking changes in changelogs
+
+### Infrastructure Pretending
+
+- In-memory storage claiming "persistence"
+- No-op security claiming "secure"
+- Console.log claiming "monitoring"
+- No circuit breakers claiming "resilient"
+
+## Verification Checklist
+
+Use this before any production claim:
+
+- [ ] `npm test` passes all tests
+- [ ] `npm run lint` shows zero errors
+- [ ] `npm run typecheck` passes
+- [ ] Database tests use real PostgreSQL/MySQL/etc.
+- [ ] Security tests validate actual controls
+- [ ] Performance tests meet SLAs
+- [ ] No TODO/PLACEHOLDER/MOCK_DATA in src/
+- [ ] Coverage reports show adequate thresholds
+- [ ] CI/CD pipeline passes
+- [ ] Deployment docs exist and are tested
+- [ ] Documentation matches code reality
+
+**If ANY box is unchecked, do not claim production readiness.**

package/dist/templates/.cursor/rules/01-working-style.mdc

@@ -0,0 +1,50 @@
+---
+description: Default agent behavior, edit style, and risk limits
+globs:
+alwaysApply: true
+---
+
+# Working Style & Risk Limits
+
+## Intent
+
+Prefer directly applying fixes over explaining. Explanations are secondary unless asked, or when a change is **risky** (see Risk Gate).
+
+## Edit Principles
+
+- **Small, bounded diffs.** Keep edits minimal, cohesive, and reviewable.
+- **Edit existing modules over forking.** Prefer refactor + rename to duplication.
+- **Preserve public behavior** unless the task explicitly requests behavioral change.
+
+## Ask-First Triggers (Risk Gate)
+
+Before editing, _ask with a Targeted Edit Plan_ if any are true:
+
+- Changes cross package boundaries or public APIs.
+- Requires deleting files or renaming public symbols.
+- Introduces a new dependency or build tool.
+- Affects security, persistence, auth, or infra.
+- Touches > 10 files or > 300 LOC.
+
+**Targeted Edit Plan (TEP)** must include:
+
+- Scope (files, symbols), risks, rollback notes.
+- Tests to run/update.
+- Acceptance checks (what passing looks like).
+
+## Diff Hygiene
+
+- Keep each commit focused on one intent.
+- Include brief rationale in the commit subject (≤72 chars).
+- Never bypass pre-commit hooks; `--no-verify` is **forbidden**.
+
+## When to Explain
+
+- On TEP prompts, on rejected edits, or when trade-offs are non-obvious.
+- Keep explanations concise and adjacent to the diff.
+
+## Acceptance (per PR)
+
+- Tests + lints pass locally.
+- No widened public API surface without TEP.
+- No dead code or duplicate modules introduced.

package/dist/templates/.cursor/rules/02-quality-gates.mdc

@@ -0,0 +1,370 @@
+---
+description: Comprehensive testing standards and verification requirements
+globs:
+alwaysApply: true
+---
+
+# Testing Standards & Verification Requirements
+
+## Testing Pyramid Requirements
+
+### Unit Tests (Foundation Layer)
+
+- **Coverage Thresholds**: 80% line coverage, 90% branch coverage minimum
+- **Test Isolation**: Each test completely independent, no shared state
+- **Mock Strategy**: Mock external dependencies, test business logic in isolation
+- **Naming Convention**: `describe('ComponentName', () => { it('should do something', () => {}) })`
+- **Assertion Style**: Use descriptive assertions, avoid generic `toBe(true)`
+
+### Integration Tests (Middle Layer)
+
+- **Database Integration**: Real database connections, not mocked
+- **External APIs**: Test actual HTTP calls with proper error handling
+- **Component Communication**: Test inter-component contracts
+- **Setup/Teardown**: Proper database seeding and cleanup
+- **Async Handling**: All async operations properly awaited and tested
+
+### End-to-End Tests (Top Layer)
+
+- **Full User Journeys**: Complete workflows from start to finish
+- **Real Browsers**: Use actual browser automation, not mocked DOM
+- **Data Persistence**: Verify data survives application restarts
+- **Performance Baselines**: Include timing assertions where relevant
+
+## Test Quality Standards
+
+### Test Structure Requirements
+
+```typescript
+describe('ComponentName', () => {
+  describe('when condition A', () => {
+    it('should behave correctly', () => {
+      // Given: Setup preconditions
+      // When: Execute the action
+      // Then: Verify the outcome
+    });
+  });
+});
+```
+
+### Edge Case Coverage
+
+- **Null/Undefined**: Test with null, undefined, empty arrays, empty objects
+- **Boundary Values**: Test minimums, maximums, and edge boundaries
+- **Error Conditions**: Test all error paths and exception handling
+- **Concurrency**: Test race conditions and concurrent access
+- **Resource Limits**: Test memory limits, timeouts, rate limits
+
+### Test Data Management
+
+- **Realistic Fixtures**: Use representative data, not just minimal examples
+- **Factory Pattern**: Create test data factories for consistent object creation
+- **Cleanup Strategy**: Ensure tests don't leave persistent state
+- **Isolation**: Tests must not interfere with each other
+
+## Verification Requirements
+
+### Pre-Commit Verification
+
+- [ ] All unit tests pass (`npm test`)
+- [ ] No tests skipped in production code
+- [ ] Coverage thresholds met
+- [ ] No console errors or warnings in tests
+- [ ] Database tests use real connections
+
+### Integration Verification
+
+- [ ] Database schema matches migrations
+- [ ] External API contracts validated
+- [ ] Authentication/authorization tested
+- [ ] Error handling verified end-to-end
+
+### Performance Verification
+
+- [ ] Response times within documented SLAs
+- [ ] Memory usage within limits
+- [ ] Database query performance acceptable
+- [ ] Concurrent user load handled
+
+## Test Infrastructure Standards
+
+### Testing Tools & Frameworks
+
+- **Test Runner**: Jest, Vitest, or equivalent with parallel execution
+- **Assertion Library**: Built-in assertions with descriptive matchers
+- **Mocking**: Comprehensive mocking for external dependencies
+- **Coverage**: Istanbul/NYC for coverage reporting
+- **CI Integration**: Automated test execution in CI pipeline
+
+### Database Testing
+
+- **Test Database**: Separate database instance for tests
+- **Schema Sync**: Automatic schema setup/teardown
+- **Data Seeding**: Deterministic test data seeding
+- **Transaction Rollback**: Tests wrapped in transactions for cleanup
+
+### CI/CD Testing
+
+- **Parallel Execution**: Tests run in parallel for speed
+- **Flaky Test Detection**: Automatic retry for known flaky tests
+- **Coverage Reporting**: Coverage reports uploaded to CI
+- **Test Result Storage**: Historical test results tracked
+
+## Testing Anti-Patterns (Forbidden)
+
+### ❌ Mocking Core Business Logic
+
+```typescript
+// DON'T: Mock the function you're supposed to test
+jest.mock('./businessLogic', () => ({
+  calculateTotal: jest.fn(() => 100),
+}));
+
+test('calculateTotal', () => {
+  expect(calculateTotal()).toBe(100); // Tests the mock, not the logic
+});
+```
+
+### ❌ Testing Implementation Details
+
+```typescript
+// DON'T: Test private methods or internal state
+test('internal counter increments', () => {
+  component.privateCounter = 5; // Accessing private state
+  expect(component.privateCounter).toBe(5);
+});
+```
+
+### ❌ Inadequate Error Testing
+
+```typescript
+// DON'T: Generic error testing
+test('throws error', () => {
+  expect(() => riskyOperation()).toThrow(); // Too vague
+});
+```
+
+### ❌ No Cleanup in Integration Tests
+
+```typescript
+// DON'T: Leave test data behind
+test('creates user', async () => {
+  await createUser({ name: 'test' });
+  // No cleanup - data persists
+});
+```
+
+## Testing Best Practices
+
+### ✅ Proper Error Testing
+
+```typescript
+test('throws specific error for invalid input', () => {
+  expect(() => validateEmail('invalid')).toThrow(ValidationError);
+  expect(() => validateEmail('invalid')).toThrow('Invalid email format');
+});
+```
+
+### ✅ Realistic Test Data
+
+```typescript
+const realisticUser = {
+  id: 'user-123',
+  email: 'user@example.com',
+  name: 'John Doe',
+  createdAt: new Date('2024-01-01'),
+  preferences: { theme: 'dark', notifications: true },
+};
+```
+
+### ✅ Proper Async Testing
+
+```typescript
+test('resolves with correct data', async () => {
+  const result = await fetchUserData('user-123');
+  expect(result).toEqual(expectedUserData);
+});
+```
+
+### ✅ Database Test Cleanup
+
+```typescript
+describe('UserService', () => {
+  let dbClient;
+
+  beforeEach(async () => {
+    dbClient = await createTestDbConnection();
+    await seedTestData(dbClient);
+  });
+
+  afterEach(async () => {
+    await cleanupTestData(dbClient);
+    await dbClient.end();
+  });
+});
+```
+
+## Test Documentation Requirements
+
+### Test Comments for Complex Logic
+
+```typescript
+test('calculates compound interest with monthly compounding', () => {
+  // Formula: A = P(1 + r/n)^(nt)
+  // Where: A = final amount, P = principal, r = rate, n = compounding frequency, t = time
+  const principal = 1000;
+  const rate = 0.05; // 5%
+  const compoundingFrequency = 12; // monthly
+  const timeInYears = 2;
+
+  const result = calculateCompoundInterest(principal, rate, compoundingFrequency, timeInYears);
+  const expected = 1104.54; // Pre-calculated expected value
+
+  expect(result).toBeCloseTo(expected, 2);
+});
+```
+
+### Test Coverage Comments
+
+```typescript
+// Test Coverage:
+// ✅ Happy path: valid input -> correct output
+// ✅ Edge case: zero principal -> zero result
+// ✅ Edge case: negative rate -> throws error
+// ✅ Error case: invalid compounding frequency -> throws error
+// ✅ Boundary: very large numbers -> handles precision
+```
+
+## Performance Testing Standards
+
+### Response Time Assertions
+
+```typescript
+test('responds within SLA', async () => {
+  const startTime = Date.now();
+  const result = await expensiveOperation();
+  const duration = Date.now() - startTime;
+
+  expect(duration).toBeLessThan(5000); // 5 second SLA
+  expect(result).toBeDefined();
+});
+```
+
+### Load Testing Guidelines
+
+- Test with realistic concurrent users
+- Include warm-up periods
+- Measure 95th percentile response times
+- Test memory usage under load
+- Verify graceful degradation
+
+## Mutation Testing Standards
+
+### Mutation Operators to Cover
+
+- **Arithmetic Operators**: `+`, `-`, `*`, `/`, `%`
+- **Logical Operators**: `&&`, `||`, `!`
+- **Comparison Operators**: `==`, `!=`, `<`, `>`, `<=`, `>=`
+- **Conditional Boundaries**: `if` conditions, ternary operators
+- **Return Statements**: Missing/incorrect returns
+- **Variable Assignments**: Wrong variable assignments
+
+### Mutation Score Targets
+
+- **Critical Components**: 80%+ mutation score
+- **Business Logic**: 70%+ mutation score
+- **Utilities**: 60%+ mutation score
+- **UI Components**: 50%+ mutation score (may be lower due to test complexity)
+
+## Accessibility Testing (Web Components)
+
+### Screen Reader Testing
+
+```typescript
+test("is accessible to screen readers", () => {
+  render(<Button>Click me</Button>);
+
+  // Test ARIA labels
+  expect(screen.getByRole("button")).toHaveAttribute("aria-label", "Click me");
+
+  // Test keyboard navigation
+  userEvent.tab();
+  expect(screen.getByRole("button")).toHaveFocus();
+});
+```
+
+### Color Contrast Testing
+
+```typescript
+test("meets color contrast requirements", () => {
+  render(<Text variant="error">Error message</Text>);
+
+  const element = screen.getByText("Error message");
+  const styles = window.getComputedStyle(element);
+
+  // Verify contrast ratio programmatically
+  expect(
+    getContrastRatio(styles.color, styles.backgroundColor)
+  ).toBeGreaterThan(4.5);
+});
+```
+
+## Execution Discipline
+
+- Run unit tests and lints after any major change; iterate until green.
+- If the project defines an engine, confirm Node version via console before running scripts.
+- `.env` files exist; do **not** attempt to cat protected dotfiles. Use framework tooling or documented env loaders.
+
+## Commits
+
+- `--no-verify` is **not allowed**. If hooks fail, **fix the cause** or split work into smaller audited commits.
+- Commit subjects: **what + why** in one sentence. Bodies for context only when needed.
+
+## TODOs & Placeholders
+
+Tag placeholders explicitly in code:
+
+- `// TODO: ...` (critical, must block if reached)
+- `// PLACEHOLDER: ...` (non-critical placeholder, warn)
+- `// MOCK DATA: ...` (remove before release)
+
+**Critical TODOs**: throw at execution site with clear message.
+
+## Diagrams/Charts
+
+- In Markdown, use **Mermaid** only. Ensure contrast (dark text on light, light on dark backgrounds).
+
+## CAWS Integration
+
+### Quality Gate Commands
+
+```bash
+# Run comprehensive test suite
+caws quality-gates --test-coverage --mutation-testing
+
+# Check test quality metrics
+caws metrics track --metric="test_coverage" --value=85
+caws metrics track --metric="mutation_score" --value=70
+
+# Update progress with test completion
+caws progress update --criterion-id="TEST-001" --status="completed" --tests-passing=25
+```
+
+### Test Analysis
+
+```bash
+# Analyze test patterns and budget prediction
+caws test-analysis assess-budget
+caws test-analysis analyze-patterns
+caws test-analysis find-similar
+```
+
+## Acceptance
+
+- `test`, `lint`, `typecheck` succeed.
+- No TODOs executed at runtime.
+- No style violations flagged by project linters.
+- Coverage thresholds met (80%+ line, 90%+ branch)
+- Mutation testing scores meet targets (70%+ for critical components)
+- All integration tests use real database connections
+- Performance tests meet documented SLAs

package/dist/templates/.cursor/rules/03-naming-and-refactor.mdc

@@ -0,0 +1,33 @@
+---
+description: Canonical naming; forbid enhanced/new/final forks; refactor rules
+globs:
+alwaysApply: true
+---
+
+# Canonical Naming & Refactor Rules
+
+## No Duplicate/Fork Names
+
+Reject or remove modules/files named with these modifiers:
+`enhanced | unified | better | new | next | final | copy | revamp | improved` (case-insensitive).
+
+**Pre-flight check (human-run or agent-run shell):**
+
+```bash
+rg -n --no-ignore -g '!node_modules' '(?i)\b(enhanced|unified|better|new|next|final|copy|revamp|improved)\b'
+rg -n --no-ignore -g '!node_modules' '(?i)(enhanced|unified|new|final|copy).*\.([tj]sx?|mjs|cjs|mts|cts)$'
+```
+
+If hits exist in proposed filenames/symbols: **do not proceed**. Use **purpose-first canonical names** and edit the existing module.
+
+## Refactor Strategy
+
+- **Merge, then delete**: If two files cover one domain, merge into the canonical name, update imports, remove the duplicate.
+- Prefer **Strategy** + feature flags over file forks.
+- Every refactor must include tests proving no behavior change (or updated tests + CHANGELOG if behavior changes).
+
+## Acceptance
+
+- No banned modifiers present in filenames or public symbols.
+- Imports updated; build is green.
+- Duplicates removed from tree.

package/dist/templates/.cursor/rules/04-logging-language-style.mdc

@@ -0,0 +1,23 @@
+---
+description: Logging, language tone, emoji policy
+globs:
+alwaysApply: true
+---
+
+# Logging & Language
+
+## Clarity over chronology
+
+Remove "phase/week" phrasing in docs/logs. State the **specific improvement**:
+
+- ❌ "PHASE 1 optimization"
+- ✅ "Initialize workload analyzer for parallelization"
+
+## Emojis
+
+- Emojis are banned across code, docs, and commits.
+- Exception (debug logs only): ⚠️, ✅, 🚫.
+
+## Commit Tone
+
+Professional, neutral, and specific. Avoid hype or vague framing.

package/dist/templates/.cursor/rules/05-safe-defaults-guards.mdc

@@ -0,0 +1,23 @@
+---
+description: Safe defaults, guard clauses, early returns
+globs:
+alwaysApply: false
+---
+
+# Safe Defaults & Guard Clauses
+
+## Intent
+
+Minimize null/undefined faults and nesting.
+
+## Guidelines (language-agnostic)
+
+- Prefer **guard clauses** at top of function to fail fast.
+- Default parameter objects in signatures.
+- Prefer **short-circuiting** / optional access / null-coalescing where supported.
+- Loop defensively on possibly-empty collections.
+
+## Acceptance
+
+- No deep nesting introduced where guard clauses apply.
+- Inputs validated at boundaries; failures are explicit and early.

package/dist/templates/.cursor/rules/06-typescript-conventions.mdc

@@ -0,0 +1,36 @@
+---
+description: TypeScript/JS conventions (alias imports, const, types source of truth)
+globs:
+  - '**/*.ts'
+  - '**/*.tsx'
+  - '**/*.mts'
+  - '**/*.cts'
+alwaysApply: false
+---
+
+# TS/JS Conventions
+
+## Variables
+
+- Prefer `const` over `let` where possible.
+
+## Imports
+
+- Use aliased imports from `@/` (mapped to `src`).
+- Replace deep relative paths (`../../x`) with `@/...` when available.
+
+## Types
+
+- Single source of truth at `src/types`.
+- Before creating a new type, check and extend the canonical definition.
+- Avoid duplicate declarations; prefer composition or augmentation.
+
+## Modularity
+
+- As files approach ~1000 LOC, evaluate separation of concerns; extract cohesive units.
+
+## Acceptance
+
+- No unnecessary `let`.
+- No duplicate type declarations.
+- No deep relative paths where alias exists.

package/dist/templates/.cursor/rules/07-process-ops.mdc

@@ -0,0 +1,20 @@
+---
+description: Process discipline for local servers and hung commands
+globs:
+alwaysApply: true
+---
+
+# Process Discipline
+
+## Servers
+
+- Before starting a dev server, check if one is already running on the port; reuse or stop it to avoid duplicates.
+- If multiple processes are attached to the port, list and kill explicitly; document PIDs in the PR note if non-obvious.
+
+## Hung/Canceled Commands
+
+If a command is canceled or stalls:
+
+1. Assume it hung or waited for input.
+2. Re-run with verbose/debug flags.
+3. Surface the prompt/interaction in the PR so reviewers understand the resolution.