@paths.design/caws-cli 3.5.0 → 4.1.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.1.0",
   "description": "CAWS CLI - Coding Agent Workflow System command line tools",
   "main": "dist/index.js",
   "bin": {
@@ -13,7 +13,7 @@
     "templates"
   ],
   "scripts": {
-    "build": "mkdir -p dist && cp -r src/* dist/ && npm run typecheck",
+    "build": "mkdir -p dist && cp -r src/* dist/",
     "dev": "mkdir -p dist && cp -r src/* dist/ && node dist/index.js",
     "typecheck": "tsc --emitDeclarationOnly --outDir dist",
     "start": "node dist/index.js",
@@ -51,12 +51,10 @@
     "directory": "packages/caws-cli"
   },
   "dependencies": {
-    "ajv": "^8.12.0",
     "chalk": "4.1.2",
     "commander": "^11.0.0",
     "fs-extra": "^11.0.0",
-    "inquirer": "8.2.7",
-    "js-yaml": "4.1.0"
+    "inquirer": "8.2.7"
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",
@@ -68,10 +66,13 @@
     "@types/inquirer": "^8.2.6",
     "@types/js-yaml": "^4.0.0",
     "@types/node": "^20.0.0",
+    "ajv": "8.17.1",
     "esbuild": "0.25.10",
     "eslint": "^9.0.0",
     "jest": "30.1.3",
+    "js-yaml": "4.1.0",
     "lint-staged": "15.5.2",
+    "micromatch": "4.0.8",
     "prettier": "^3.0.0",
     "semantic-release": "25.0.0-beta.6",
     "typescript": "^5.0.0"

package/templates/.cursor/hooks/caws-scope-guard.sh

@@ -13,6 +13,57 @@ FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // ""')
 # Check if CAWS is available and we have a working spec
 if command -v caws &> /dev/null && [[ -f ".caws/working-spec.yaml" ]]; then
 
+  # AGENT GUARDRAILS - Prevent policy bypass attempts
+  if [[ "$ACTION" == "edit_file" ]] || [[ "$ACTION" == "create_file" ]]; then
+    if [[ "$FILE_PATH" == ".caws/policy.yaml" ]]; then
+      echo '{
+        "userMessage": "🚫 Policy file editing blocked by agent guardrails",
+        "agentMessage": "Agents cannot edit .caws/policy.yaml - requires human dual control",
+        "block": true,
+        "suggestions": [
+          "Policy changes must be approved by humans with Gatekeeper role",
+          "Create a separate PR for policy changes",
+          "For budget exceptions: caws waivers create --title=\"Budget exception\" --reason=architectural_refactor --gates=budget_limit",
+          "Contact @gatekeepers for policy modifications"
+        ]
+      }'
+      exit 1
+    fi
+
+    if [[ "$FILE_PATH" == "CODEOWNERS" ]]; then
+      echo '{
+        "userMessage": "🚫 CODEOWNERS editing blocked by agent guardrails",
+        "agentMessage": "Agents cannot modify CODEOWNERS - governance changes require approval",
+        "block": true,
+        "suggestions": [
+          "CODEOWNERS changes require governance review",
+          "Contact repository maintainers for ownership changes",
+          "For approval workflows: caws waivers create --reason=governance_change"
+        ]
+      }'
+      exit 1
+    fi
+
+    if [[ "$FILE_PATH" == ".caws/working-spec.yaml" ]]; then
+      # Check if trying to add change_budget
+      FILE_CONTENT=$(echo "$INPUT" | jq -r '.content // ""')
+      if echo "$FILE_CONTENT" | grep -q "change_budget"; then
+        echo '{
+          "userMessage": "🚫 Budget editing blocked by agent guardrails",
+          "agentMessage": "Agents cannot introduce change_budget fields - budgets are derived automatically",
+          "block": true,
+          "suggestions": [
+            "Check current budget status: caws burnup",
+            "For budget exceptions: caws waivers create --title=\"Scope expansion\" --reason=architectural_refactor --gates=budget_limit --expires-at=\"2025-12-31T23:59:59Z\"",
+            "Add waiver_ids to working spec instead: [\"WV-XXXX\"]",
+            "Validate waiver: caws validate .caws/working-spec.yaml"
+          ]
+        }'
+        exit 1
+      fi
+    fi
+  fi
+
   # For file access actions, check scope
   if [[ "$ACTION" == "read_file" ]] || [[ "$ACTION" == "edit_file" ]] || [[ -n "$FILE_PATH" ]]; then
 
@@ -25,9 +76,10 @@ if command -v caws &> /dev/null && [[ -f ".caws/working-spec.yaml" ]]; then
         "agentMessage": "Cannot access '"$FILE_PATH"' - outside CAWS defined scope",
         "block": true,
         "suggestions": [
-          "Check CAWS working spec scope definition",
-          "Update scope in .caws/working-spec.yaml if needed",
-          "Create waiver for scope violation: caws waivers create --reason=scope_violation"
+          "Check current scope: caws validate .caws/working-spec.yaml",
+          "Update scope in working spec: edit .caws/working-spec.yaml scope.in array",
+          "For scope exceptions: caws waivers create --title=\"Scope expansion\" --reason=architectural_refactor --gates=scope_boundary --description=\"Need access to '"$FILE_PATH"' for implementation\"",
+          "Validate changes: caws validate .caws/working-spec.yaml"
         ]
       }'
       exit 1
@@ -36,8 +88,10 @@ if command -v caws &> /dev/null && [[ -f ".caws/working-spec.yaml" ]]; then
         "userMessage": "⚠️ File access outside primary scope",
         "agentMessage": "File '"$FILE_PATH"' is outside primary scope but allowed",
         "suggestions": [
-          "Consider if this file should be in primary scope",
-          "Update .caws/working-spec.yaml scope if needed"
+          "Check if needed in primary scope: edit .caws/working-spec.yaml scope.in",
+          "Consider scope implications: caws agent evaluate",
+          "Document scope decision in working spec invariants",
+          "Validate scope changes: caws validate .caws/working-spec.yaml"
         ]
       }'
     fi
@@ -63,9 +117,11 @@ if command -v caws &> /dev/null && [[ -f ".caws/working-spec.yaml" ]]; then
           "userMessage": "⚠️ Prompt references files outside CAWS scope",
           "agentMessage": "Prompt mentions out-of-scope files: '"$OUT_OF_SCOPE"'",
           "suggestions": [
-            "Focus on files within CAWS defined scope",
-            "Update working spec scope if additional files needed",
-            "Remove out-of-scope file references from prompt"
+            "Check current scope definition: caws validate .caws/working-spec.yaml",
+            "Update working spec scope: edit .caws/working-spec.yaml scope.in array",
+            "For scope exceptions: caws waivers create --title=\"Scope expansion\" --reason=architectural_refactor --gates=scope_boundary",
+            "Refocus prompt on in-scope files or request scope update approval",
+            "Validate scope changes: caws validate .caws/working-spec.yaml"
           ]
         }'
       fi

package/templates/.cursor/hooks/validate-spec.sh

@@ -16,20 +16,30 @@ FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // ""')
 
 # Only validate if working-spec.yaml was edited
 if [[ "$FILE_PATH" == *"working-spec.yaml"* ]] || [[ "$FILE_PATH" == *"working-spec.yml"* ]]; then
-  # Run CAWS validation
-  if [ -f "apps/tools/caws/validate.js" ]; then
-    if ! node apps/tools/caws/validate.js --quiet 2>/dev/null; then
-      echo '{"userMessage":"⚠️ CAWS spec validation failed. Run: caws validate --suggestions","agentMessage":"The working-spec.yaml file has validation errors. Please review and fix before continuing."}' 2>/dev/null
-      exit 0
+  echo "🔍 Validating CAWS working spec..." >&2
+
+  # Check if CAWS CLI is available
+  if command -v caws &> /dev/null; then
+    # Run CAWS validation with suggestions
+    if VALIDATION=$(caws validate "$FILE_PATH" --quiet 2>&1); then
+      echo '{"userMessage":"✅ CAWS spec validation passed","agentMessage":"Working specification is valid and complete."}' 2>/dev/null
+    else
+      # Get suggestions for fixing the spec
+      SUGGESTIONS=$(caws validate "$FILE_PATH" --suggestions 2>/dev/null | head -5 | tr '\n' '; ' | sed 's/; $//' || echo "Run caws validate --suggestions for details")
+
+      echo '{
+        "userMessage": "⚠️ CAWS spec validation failed. Run: caws validate --suggestions",
+        "agentMessage": "The working-spec.yaml file has validation errors. Please review and fix before continuing.",
+        "suggestions": [
+          "Run caws validate --suggestions for detailed error messages",
+          "Check required fields: id, title, risk_tier, mode",
+          "Ensure acceptance criteria are properly defined",
+          "Verify scope boundaries are appropriate"
+        ]
+      }' 2>/dev/null
     fi
   else
-    # Fallback: try caws CLI
-    if command -v caws &> /dev/null; then
-      if ! caws validate --quiet 2>/dev/null; then
-        echo '{"userMessage":"⚠️ CAWS spec validation failed. Run: caws validate --suggestions","agentMessage":"The working-spec.yaml file has validation errors."}' 2>/dev/null
-        exit 0
-      fi
-    fi
+    echo '{"userMessage":"⚠️ CAWS CLI not available for validation","agentMessage":"Install CAWS CLI for automatic spec validation: npm install -g @caws/cli"}' 2>/dev/null
   fi
 fi
 

package/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.**