@paths.design/caws-cli 3.5.0 → 4.0.0

package/dist/validation/spec-validation.js

@@ -190,8 +190,9 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
       });
     }
 
-    // Validate risk tier
+    // Validate risk tier with enhanced auto-fix
     if (spec.risk_tier !== undefined && (spec.risk_tier < 1 || spec.risk_tier > 3)) {
+      const fixedValue = Math.max(1, Math.min(3, spec.risk_tier || 2));
       errors.push({
         instancePath: '/risk_tier',
         message: 'Risk tier must be 1, 2, or 3',
@@ -199,7 +200,99 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
           'Tier 1: Critical (auth, billing), Tier 2: Standard (features), Tier 3: Low risk (UI)',
         canAutoFix: true,
       });
-      fixes.push({ field: 'risk_tier', value: Math.max(1, Math.min(3, spec.risk_tier || 2)) });
+      fixes.push({
+        field: 'risk_tier',
+        value: fixedValue,
+        description: `Clamping risk_tier from ${spec.risk_tier} to valid range [1-3]: ${fixedValue}`,
+        reason: 'Risk tier out of bounds',
+      });
+    }
+
+    // Auto-fix empty arrays with sensible defaults
+    if (!spec.invariants || spec.invariants.length === 0) {
+      if (autoFix) {
+        fixes.push({
+          field: 'invariants',
+          value: ['System must remain operational during changes'],
+          description: 'Adding default invariant for empty invariants array',
+          reason: 'Invariants array was empty',
+        });
+      }
+    }
+
+    if (!spec.acceptance || spec.acceptance.length === 0) {
+      if (autoFix) {
+        fixes.push({
+          field: 'acceptance',
+          value: [
+            {
+              id: 'A1',
+              given: 'the system is in a valid state',
+              when: 'the change is applied',
+              then: 'the system remains functional',
+            },
+          ],
+          description: 'Adding placeholder acceptance criteria',
+          reason: 'Acceptance criteria array was empty',
+        });
+      }
+    }
+
+    // Auto-fix missing scope.out
+    if (spec.scope && !spec.scope.out) {
+      fixes.push({
+        field: 'scope.out',
+        value: ['node_modules/', 'dist/', '.git/'],
+        description: 'Adding default exclusions to scope.out',
+        reason: 'scope.out was missing',
+      });
+    }
+
+    // Auto-fix missing mode
+    if (!spec.mode) {
+      fixes.push({
+        field: 'mode',
+        value: 'feature',
+        description: 'Setting default mode to "feature"',
+        reason: 'mode field was missing',
+      });
+    }
+
+    // Auto-fix missing blast_radius
+    if (!spec.blast_radius) {
+      fixes.push({
+        field: 'blast_radius',
+        value: {
+          modules: [],
+          data_migration: false,
+        },
+        description: 'Adding empty blast_radius structure',
+        reason: 'blast_radius was missing',
+      });
+    }
+
+    // Auto-fix missing non_functional
+    if (!spec.non_functional) {
+      fixes.push({
+        field: 'non_functional',
+        value: {
+          a11y: [],
+          perf: {},
+          security: [],
+        },
+        description: 'Adding empty non_functional requirements structure',
+        reason: 'non_functional was missing',
+      });
+    }
+
+    // Auto-fix missing contracts
+    if (!spec.contracts) {
+      fixes.push({
+        field: 'contracts',
+        value: [],
+        description: 'Adding empty contracts array',
+        reason: 'contracts field was missing',
+      });
     }
 
     // Validate scope.in is not empty
@@ -241,6 +334,40 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
       }
     }
 
+    // Tier 1 specific requirements (critical changes)
+    if (spec.risk_tier === 1) {
+      if (!spec.observability) {
+        errors.push({
+          instancePath: '/observability',
+          message: 'Observability required for Tier 1 changes',
+          suggestion: 'Define logging, metrics, and tracing strategy',
+          canAutoFix: false,
+        });
+      }
+
+      if (!spec.rollback || spec.rollback.length === 0) {
+        errors.push({
+          instancePath: '/rollback',
+          message: 'Rollback procedures required for Tier 1 changes',
+          suggestion: 'Document rollback steps and data migration reversal',
+          canAutoFix: false,
+        });
+      }
+
+      if (
+        !spec.non_functional ||
+        !spec.non_functional.security ||
+        spec.non_functional.security.length === 0
+      ) {
+        errors.push({
+          instancePath: '/non_functional/security',
+          message: 'Security requirements required for Tier 1 changes',
+          suggestion: 'Define authentication, authorization, and data protection requirements',
+          canAutoFix: false,
+        });
+      }
+    }
+
     // Validate waiver_ids format if present
     if (spec.waiver_ids) {
       if (!Array.isArray(spec.waiver_ids)) {
@@ -256,7 +383,7 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
             errors.push({
               instancePath: '/waiver_ids',
               message: `Invalid waiver ID format: ${waiverId}`,
-              suggestion: 'Use format: WV-XXXX (e.g., WV-0001)',
+              suggestion: 'Use format: WV-XXXX where XXXX is exactly 4 digits (e.g., WV-0001)',
               canAutoFix: false,
             });
           }
@@ -264,6 +391,17 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
       }
     }
 
+    // Warn if change_budget is present (deprecated/informational only)
+    if (spec.change_budget) {
+      warnings.push({
+        instancePath: '/change_budget',
+        message:
+          'change_budget field in working spec is informational only and not used for validation',
+        suggestion:
+          'Budget is derived from policy.yaml risk_tier + waivers. This field is auto-calculated.',
+      });
+    }
+
     // Derive and check budget if requested
     let budgetCheck = null;
     if (checkBudget && projectRoot) {
@@ -288,6 +426,16 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
               canAutoFix: false,
             });
           }
+
+          // Suggest adding waiver_ids if budget exceeded and none referenced
+          if (!spec.waiver_ids || spec.waiver_ids.length === 0) {
+            warnings.push({
+              instancePath: '/waiver_ids',
+              message: 'Budget exceeded but no waivers referenced',
+              suggestion:
+                'Add waiver_ids: ["WV-0001"] to working spec, then create waiver file with: caws waiver create',
+            });
+          }
         }
       } catch (error) {
         warnings.push({
@@ -298,27 +446,55 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
       }
     }
 
-    // Apply auto-fixes if requested
+    // Apply auto-fixes if requested and not in dry-run mode
+    const { dryRun = false } = options;
+    let appliedFixes = [];
+
     if (autoFix && fixes.length > 0) {
-      console.log('🔧 Applying auto-fixes...');
-      for (const fix of fixes) {
-        const pathParts = fix.field.split('.');
-        let current = spec;
-        for (let i = 0; i < pathParts.length - 1; i++) {
-          if (!current[pathParts[i]]) current[pathParts[i]] = {};
-          current = current[pathParts[i]];
+      if (dryRun) {
+        console.log('🔍 Auto-fix preview (dry-run mode):');
+        for (const fix of fixes) {
+          console.log(`   [WOULD FIX] ${fix.field}`);
+          console.log(`      Description: ${fix.description}`);
+          console.log(`      Reason: ${fix.reason}`);
+          console.log(
+            `      Value: ${typeof fix.value === 'object' ? JSON.stringify(fix.value) : fix.value}`
+          );
+          console.log('');
+        }
+      } else {
+        console.log('🔧 Applying auto-fixes...');
+        for (const fix of fixes) {
+          try {
+            const pathParts = fix.field.split('.');
+            let current = spec;
+            for (let i = 0; i < pathParts.length - 1; i++) {
+              if (!current[pathParts[i]]) current[pathParts[i]] = {};
+              current = current[pathParts[i]];
+            }
+            current[pathParts[pathParts.length - 1]] = fix.value;
+            appliedFixes.push(fix);
+            console.log(`   ✅ Fixed ${fix.field}`);
+            console.log(`      ${fix.description}`);
+          } catch (error) {
+            console.warn(`   ⚠️  Failed to apply fix for ${fix.field}: ${error.message}`);
+          }
         }
-        current[pathParts[pathParts.length - 1]] = fix.value;
-        console.log(`   Fixed ${fix.field}: ${fix.value}`);
       }
     }
 
+    // Calculate compliance score (0-1 scale)
+    const complianceScore = calculateComplianceScore(errors, warnings);
+
     return {
       valid: errors.length === 0,
       errors,
       warnings,
       fixes: fixes.length > 0 ? fixes : undefined,
+      appliedFixes: appliedFixes.length > 0 ? appliedFixes : undefined,
+      dryRun,
       budget_check: budgetCheck,
+      complianceScore,
     };
   } catch (error) {
     return {
@@ -333,6 +509,40 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
   }
 }
 
+/**
+ * Calculate compliance score based on errors and warnings
+ * Score ranges from 0 (many issues) to 1 (perfect)
+ * @param {Array} errors - Validation errors
+ * @param {Array} warnings - Validation warnings
+ * @returns {number} Compliance score (0-1)
+ */
+function calculateComplianceScore(errors, warnings) {
+  // Start at perfect score
+  let score = 1.0;
+
+  // Each error reduces score by 0.2
+  score -= errors.length * 0.2;
+
+  // Each warning reduces score by 0.1
+  score -= warnings.length * 0.1;
+
+  // Floor at 0
+  return Math.max(0, score);
+}
+
+/**
+ * Get compliance grade from score
+ * @param {number} score - Compliance score (0-1)
+ * @returns {string} Grade (A, B, C, D, F)
+ */
+function getComplianceGrade(score) {
+  if (score >= 0.9) return 'A';
+  if (score >= 0.8) return 'B';
+  if (score >= 0.7) return 'C';
+  if (score >= 0.6) return 'D';
+  return 'F';
+}
+
 /**
  * Get suggestion for a missing field
  * @param {string} field - Field name
@@ -373,4 +583,6 @@ module.exports = {
   validateWorkingSpecWithSuggestions,
   getFieldSuggestion,
   canAutoFixField,
+  calculateComplianceScore,
+  getComplianceGrade,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "3.5.0",
+  "version": "4.0.0",
   "description": "CAWS CLI - Coding Agent Workflow System command line tools",
   "main": "dist/index.js",
   "bin": {

package/templates/.cursor/rules/01-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.**