@paths.design/caws-cli 7.0.1 → 7.0.3

package/dist/validation/spec-validation.js

@@ -238,6 +238,42 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
       }
     }
 
+    // Validate scope.out doesn't contain glob patterns
+    if (spec.scope && spec.scope.out && Array.isArray(spec.scope.out)) {
+      const globPatterns = spec.scope.out.filter(
+        (pattern) => pattern.includes('*') || pattern.includes('?')
+      );
+      if (globPatterns.length > 0) {
+        errors.push({
+          instancePath: '/scope/out',
+          message: `Unsupported glob patterns in scope.out: ${globPatterns.join(', ')}`,
+          suggestion:
+            'Use directory paths only (e.g., __pycache__/ instead of *.pyc or **/*.pyc). Python cache files are already covered by __pycache__/',
+          canAutoFix: true,
+        });
+
+        // Auto-fix: remove glob patterns and keep only directory paths
+        if (autoFix) {
+          const fixedOut = spec.scope.out
+            .filter((pattern) => !pattern.includes('*') && !pattern.includes('?'))
+            .map((pattern) => {
+              // Ensure directory paths end with /
+              if (!pattern.includes('.') && !pattern.endsWith('/')) {
+                return pattern + '/';
+              }
+              return pattern;
+            });
+
+          fixes.push({
+            field: 'scope.out',
+            value: fixedOut,
+            description: `Removed glob patterns from scope.out: ${globPatterns.join(', ')}`,
+            reason: 'Glob patterns are not supported in scope.out',
+          });
+        }
+      }
+    }
+
     // Auto-fix missing scope.out
     if (spec.scope && !spec.scope.out) {
       fixes.push({
@@ -325,11 +361,36 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
     // Tier-specific validations
     if (spec.risk_tier === 1 || spec.risk_tier === 2) {
       if (!spec.contracts || spec.contracts.length === 0) {
+        const isChoreMode = spec.mode === 'chore';
+        const suggestion = isChoreMode
+          ? 'For infrastructure/setup work, add a minimal project_setup contract or create a waiver'
+          : 'Add API contracts (OpenAPI, GraphQL, etc.) or change mode to "chore" for maintenance work';
+
         errors.push({
           instancePath: '/contracts',
-          message: 'Contracts required for Tier 1 and 2 changes',
-          suggestion: 'Specify API contracts (OpenAPI, GraphQL, etc.)',
+          message: `Contracts required for Tier ${spec.risk_tier} changes`,
+          suggestion: suggestion,
           canAutoFix: false,
+          example: isChoreMode
+            ? {
+                contracts: [
+                  {
+                    type: 'project_setup',
+                    path: '.caws/working-spec.yaml',
+                    description:
+                      'Project-level CAWS configuration. Feature-specific contracts will be added as features are developed.',
+                  },
+                ],
+              }
+            : {
+                contracts: [
+                  {
+                    type: 'openapi',
+                    path: 'docs/api/feature.yaml',
+                    version: '1.0.0',
+                  },
+                ],
+              },
         });
       }
     }
@@ -368,6 +429,48 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
       }
     }
 
+    // Validate rollback format if present (for all tiers)
+    if (spec.rollback !== undefined) {
+      if (!Array.isArray(spec.rollback)) {
+        errors.push({
+          instancePath: '/rollback',
+          message: 'rollback must be an array of strings',
+          suggestion: 'Use format: ["Step 1", "Step 2", "Step 3"]',
+          canAutoFix: false,
+        });
+      } else {
+        // Check for duplicates
+        const uniqueSteps = [...new Set(spec.rollback)];
+        if (uniqueSteps.length !== spec.rollback.length) {
+          warnings.push({
+            instancePath: '/rollback',
+            message: 'Duplicate entries found in rollback array',
+            suggestion: 'Remove duplicate entries',
+          });
+
+          if (autoFix) {
+            fixes.push({
+              field: 'rollback',
+              value: uniqueSteps,
+              description: 'Removed duplicate rollback entries',
+              reason: 'Duplicate entries detected',
+            });
+          }
+        }
+
+        // Validate each entry is a string
+        const invalidEntries = spec.rollback.filter((entry) => typeof entry !== 'string');
+        if (invalidEntries.length > 0) {
+          errors.push({
+            instancePath: '/rollback',
+            message: `Invalid rollback entries (must be strings): ${invalidEntries.length}`,
+            suggestion: 'All rollback entries must be string descriptions',
+            canAutoFix: false,
+          });
+        }
+      }
+    }
+
     // Validate waiver_ids format if present
     if (spec.waiver_ids) {
       if (!Array.isArray(spec.waiver_ids)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "7.0.1",
+  "version": "7.0.3",
   "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/",
+    "build": "mkdir -p dist && cp -r src/* dist/ && cp -r templates dist/ 2>/dev/null || true",
     "dev": "mkdir -p dist && cp -r src/* dist/ && node dist/index.js",
     "typecheck": "tsc --emitDeclarationOnly --outDir dist",
     "start": "node dist/index.js",

package/templates/.caws/schemas/waivers.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CAWS Waivers Configuration",
+  "type": "object",
+  "patternProperties": {
+    ".*": {
+      "type": "object",
+      "required": ["gate", "reason", "owner", "expiry"],
+      "properties": {
+        "gate": {
+          "type": "string",
+          "enum": ["coverage", "mutation", "contracts", "a11y", "perf", "security"]
+        },
+        "reason": { "type": "string", "minLength": 10 },
+        "owner": { "type": "string" },
+        "expiry": { "type": "string", "format": "date-time" },
+        "compensating_control": { "type": "string" },
+        "ticket_url": { "type": "string", "format": "uri" },
+        "approved_by": { "type": "string" },
+        "created_at": { "type": "string", "format": "date-time" },
+        "status": {
+          "type": "string",
+          "enum": ["active", "expired", "revoked"],
+          "default": "active"
+        }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/templates/.caws/schemas/working-spec.schema.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CAWS Working Spec",
+  "type": "object",
+  "required": [
+    "id",
+    "title",
+    "risk_tier",
+    "mode",
+    "blast_radius",
+    "operational_rollback_slo",
+    "scope",
+    "invariants",
+    "acceptance",
+    "non_functional",
+    "contracts"
+  ],
+  "properties": {
+    "id": { "type": "string", "pattern": "^(PROJ|FEAT|FIX|ARCH)-\\d{4}$" },
+    "title": { "type": "string", "minLength": 10, "maxLength": 200 },
+    "risk_tier": { "type": ["integer", "string"], "enum": [1, 2, 3, "1", "2", "3"] },
+    "mode": { "type": "string", "enum": ["feature", "refactor", "fix", "doc", "chore"] },
+    "waiver_ids": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^WV-\\d{4}$" },
+      "description": "IDs of active waivers applying to this spec"
+    },
+    "blast_radius": {
+      "type": "object",
+      "required": ["modules"],
+      "properties": {
+        "modules": { "type": "array", "items": { "type": "string" } },
+        "data_migration": { "type": "boolean" }
+      }
+    },
+    "operational_rollback_slo": { "type": "string" },
+    "scope": {
+      "type": "object",
+      "required": ["in", "out"],
+      "properties": {
+        "in": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+        "out": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "invariants": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "acceptance": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "given", "when", "then"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^A\\d+$" },
+          "given": { "type": "string" },
+          "when": { "type": "string" },
+          "then": { "type": "string" }
+        }
+      }
+    },
+    "non_functional": {
+      "type": "object",
+      "properties": {
+        "a11y": { "type": "array", "items": { "type": "string" } },
+        "perf": {
+          "type": "object",
+          "properties": {
+            "api_p95_ms": { "type": "integer", "minimum": 1 },
+            "lcp_ms": { "type": "integer", "minimum": 1 }
+          },
+          "additionalProperties": false
+        },
+        "security": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "contracts": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["type", "path"],
+        "properties": {
+          "type": { "type": "string", "enum": ["openapi", "graphql", "proto", "pact"] },
+          "path": { "type": "string" }
+        }
+      }
+    },
+    "observability": {
+      "type": "object",
+      "properties": {
+        "logs": { "type": "array", "items": { "type": "string" } },
+        "metrics": { "type": "array", "items": { "type": "string" } },
+        "traces": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "migrations": { "type": "array", "items": { "type": "string" } },
+    "rollback": { "type": "array", "items": { "type": "string" } },
+    "experiment_mode": {
+      "type": "boolean",
+      "description": "Enables experimental mode with reduced requirements"
+    },
+    "timeboxed_hours": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Time limit for experimental features in hours"
+    },
+    "human_override": {
+      "type": "object",
+      "properties": {
+        "approved_by": { "type": "string" },
+        "reason": { "type": "string" },
+        "waived_requirements": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["mutation_testing", "contract_tests", "coverage", "manual_review"]
+          }
+        },
+        "expiry_date": { "type": "string", "format": "date-time" }
+      },
+      "required": ["approved_by", "reason"]
+    },
+    "ai_assessment": {
+      "type": "object",
+      "properties": {
+        "confidence_level": { "type": "integer", "minimum": 1, "maximum": 10 },
+        "uncertainty_areas": { "type": "array", "items": { "type": "string" } },
+        "recommended_pairing": { "type": "boolean" }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/templates/.caws/templates/working-spec.template.yml

@@ -0,0 +1,74 @@
+id: '{{FEATURE_ID}}'
+title: '{{FEATURE_TITLE}}'
+risk_tier: { { TIER } }
+scope:
+  in:
+    - '{{SCOPE_ITEM_1}}'
+    - '{{SCOPE_ITEM_2}}'
+  out:
+    - '{{OUT_OF_SCOPE_ITEM_1}}'
+invariants:
+  - '{{BUSINESS_RULE_1}}'
+  - '{{BUSINESS_RULE_2}}'
+acceptance:
+  - id: A1
+    given: '{{GIVEN_CONDITION}}'
+    when: '{{WHEN_ACTION}}'
+    then: '{{THEN_OUTCOME}}'
+    status: pending # pending | in_progress | completed
+    # Optional: detailed progress tracking
+    # tests:
+    #   written: 0
+    #   passing: 0
+    # coverage: 0.0
+    # last_updated: '2025-10-09T14:30:00Z'
+  - id: A2
+    given: '{{GIVEN_CONDITION_2}}'
+    when: '{{WHEN_ACTION_2}}'
+    then: '{{THEN_OUTCOME_2}}'
+    status: pending # pending | in_progress | completed
+    # Optional: detailed progress tracking
+    # tests:
+    #   written: 0
+    #   passing: 0
+    # coverage: 0.0
+    # last_updated: '2025-10-09T14:30:00Z'
+non_functional:
+  a11y:
+    - '{{ACCESSIBILITY_REQUIREMENT}}'
+  perf:
+    api_p95_ms: { { PERF_BUDGET } }
+    lcp_ms: { { LCP_BUDGET } }
+  security:
+    - '{{SECURITY_REQUIREMENT}}'
+contracts:
+  - type: '{{CONTRACT_TYPE}}'
+    path: '{{CONTRACT_PATH}}'
+observability:
+  logs:
+    - '{{LOG_STATEMENT}}'
+  metrics:
+    - '{{METRIC_NAME}}'
+  traces:
+    - '{{TRACE_SPAN}}'
+migrations:
+  - '{{MIGRATION_DESCRIPTION}}'
+rollback:
+  - '{{ROLLBACK_STRATEGY}}'
+# Optional: Enable for experimental features with reduced requirements
+# experiment_mode: true
+# timeboxed_hours: 24
+
+# Optional: AI confidence assessment
+# ai_assessment:
+#   confidence_level: 8
+#   uncertainty_areas: ["complex business logic", "performance implications"]
+#   recommended_pairing: false
+
+# Optional: Human override for special cases (hotfixes, urgent changes)
+# human_override:
+#   approved_by: "senior-dev-username"
+#   reason: "Urgent production fix - bypassing mutation tests for immediate deployment"
+#   waived_requirements: ["mutation_testing", "manual_review"]
+#   expiry_date: "2025-10-01T00:00:00Z"
+

package/templates/.caws/tools/README.md

@@ -0,0 +1,20 @@
+# CAWS Tools
+
+This directory contains CAWS-specific tools that aren't available in the CLI.
+
+## scope-guard.js
+
+Enforces that experimental code stays within designated sandbox areas. Used by Cursor hooks for scope validation.
+
+```bash
+# Validate experimental code containment
+node .caws/tools/scope-guard.js validate
+
+# Check containment status
+node .caws/tools/scope-guard.js check .caws/working-spec.yaml
+```
+
+**Usage in Cursor Hooks:**
+
+The `.cursor/hooks/scope-guard.sh` hook automatically uses this tool to validate file attachments against working spec scope boundaries.
+

package/templates/.caws/tools/scope-guard.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview CAWS Scope Guard
+ * Enforces that experimental code stays within designated sandbox areas
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs');
+const { execSync } = require('child_process');
+
+/**
+ * Check if experimental code is properly contained
+ * @param {string} workingSpecPath - Path to working spec file
+ * @returns {Object} Scope validation results
+ */
+function checkExperimentalContainment(workingSpecPath = '.caws/working-spec.yaml') {
+  try {
+    if (!fs.existsSync(workingSpecPath)) {
+      console.error('❌ Working spec not found:', workingSpecPath);
+      return { valid: false, errors: ['Working spec not found'] };
+    }
+
+    const yaml = require('js-yaml');
+    const spec = yaml.load(fs.readFileSync(workingSpecPath, 'utf8'));
+
+    const results = {
+      valid: true,
+      errors: [],
+      warnings: [],
+      experimentalFiles: [],
+      nonExperimentalFiles: [],
+    };
+
+    // Only check if experimental mode is enabled
+    if (!spec.experimental_mode?.enabled) {
+      console.log('ℹ️  Experimental mode not enabled - skipping containment check');
+      return results;
+    }
+
+    const sandboxLocation = spec.experimental_mode.sandbox_location || 'experimental/';
+    console.log(`🔍 Checking containment for experimental code in: ${sandboxLocation}`);
+
+    // Get list of changed files (this would typically come from git diff)
+    const changedFiles = getChangedFiles();
+
+    if (changedFiles.length === 0) {
+      console.log('ℹ️  No files changed - skipping scope check');
+      return results;
+    }
+
+    // Check each changed file
+    changedFiles.forEach((file) => {
+      const isInSandbox =
+        file.startsWith(sandboxLocation) ||
+        file.includes(`/${sandboxLocation}`) ||
+        file.includes(sandboxLocation);
+
+      if (isInSandbox) {
+        results.experimentalFiles.push(file);
+        console.log(`✅ Experimental file properly contained: ${file}`);
+      } else {
+        results.nonExperimentalFiles.push(file);
+        results.valid = false;
+        results.errors.push(`Experimental code found outside sandbox: ${file}`);
+        console.error(`❌ Experimental code outside sandbox: ${file}`);
+      }
+    });
+
+    // Check if experimental files actually exist
+    results.experimentalFiles.forEach((file) => {
+      if (!fs.existsSync(file)) {
+        results.warnings.push(`Experimental file not found (may have been deleted): ${file}`);
+        console.warn(`⚠️  Experimental file not found: ${file}`);
+      }
+    });
+
+    return results;
+  } catch (error) {
+    console.error('❌ Error checking experimental containment:', error.message);
+    return { valid: false, errors: [error.message] };
+  }
+}
+
+/**
+ * Get list of changed files from git
+ * @returns {Array} List of changed file paths
+ */
+function getChangedFiles() {
+  try {
+    // Get files that are staged or modified
+    const staged = execSync('git diff --cached --name-only', { encoding: 'utf8' })
+      .split('\n')
+      .filter((file) => file.trim());
+
+    const modified = execSync('git diff --name-only', { encoding: 'utf8' })
+      .split('\n')
+      .filter((file) => file.trim());
+
+    // Combine and deduplicate
+    const allFiles = [...new Set([...staged, ...modified])];
+
+    // Filter out deleted files (they might still be in the diff)
+    return allFiles.filter((file) => {
+      try {
+        return fs.existsSync(file);
+      } catch {
+        return false;
+      }
+    });
+  } catch (error) {
+    console.warn('⚠️  Could not get changed files from git:', error.message);
+    return [];
+  }
+}
+
+/**
+ * Validate that experimental code follows containment rules
+ * @param {string} workingSpecPath - Path to working spec file
+ */
+function validateExperimentalScope(workingSpecPath = '.caws/working-spec.yaml') {
+  console.log('🔍 Validating experimental code containment...');
+
+  const results = checkExperimentalContainment(workingSpecPath);
+
+  if (!results.valid) {
+    console.error('\n❌ Experimental containment validation failed:');
+    results.errors.forEach((error) => {
+      console.error(`   - ${error}`);
+    });
+
+    if (results.warnings.length > 0) {
+      console.warn('\n⚠️  Warnings:');
+      results.warnings.forEach((warning) => {
+        console.warn(`   - ${warning}`);
+      });
+    }
+
+    console.error('\n💡 To fix containment issues:');
+    console.error('   1. Move experimental code to the designated sandbox location');
+    console.error('   2. Update the sandbox_location in your working spec');
+    console.error('   3. Or disable experimental mode if this is production code');
+
+    process.exit(1);
+  }
+
+  if (results.warnings.length > 0) {
+    console.warn('\n⚠️  Experimental containment warnings:');
+    results.warnings.forEach((warning) => {
+      console.warn(`   - ${warning}`);
+    });
+  }
+
+  console.log('✅ Experimental code containment validated');
+  console.log(`   - Files in sandbox: ${results.experimentalFiles.length}`);
+  console.log(`   - Files outside sandbox: ${results.nonExperimentalFiles.length}`);
+}
+
+// CLI interface
+if (require.main === module) {
+  const command = process.argv[2];
+  const specPath = process.argv[3] || '.caws/working-spec.yaml';
+
+  switch (command) {
+    case 'validate':
+      validateExperimentalScope(specPath);
+      break;
+
+    case 'check':
+      const results = checkExperimentalContainment(specPath);
+      console.log('\n📊 Containment Check Results:');
+      console.log(`   Valid: ${results.valid}`);
+      console.log(`   Experimental files: ${results.experimentalFiles.length}`);
+      console.log(`   Non-experimental files: ${results.nonExperimentalFiles.length}`);
+      console.log(`   Errors: ${results.errors.length}`);
+      console.log(`   Warnings: ${results.warnings.length}`);
+
+      if (results.errors.length > 0) {
+        console.log('\n❌ Errors:');
+        results.errors.forEach((error) => console.log(`   - ${error}`));
+      }
+
+      if (results.warnings.length > 0) {
+        console.log('\n⚠️  Warnings:');
+        results.warnings.forEach((warning) => console.log(`   - ${warning}`));
+      }
+
+      process.exit(results.valid ? 0 : 1);
+      break;
+
+    default:
+      console.log('CAWS Scope Guard');
+      console.log('Usage:');
+      console.log('  node scope-guard.js validate [spec-path]');
+      console.log('  node scope-guard.js check [spec-path]');
+      console.log('');
+      console.log('Examples:');
+      console.log('  node scope-guard.js validate');
+      console.log('  node scope-guard.js check .caws/working-spec.yaml');
+      process.exit(1);
+  }
+}
+
+module.exports = {
+  checkExperimentalContainment,
+  validateExperimentalScope,
+  getChangedFiles,
+};