@paths.design/caws-cli 9.3.2 → 10.1.0

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

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "CAWS Working Spec",
   "type": "object",
   "required": [
@@ -15,119 +15,326 @@
     "non_functional",
     "contracts"
   ],
+  "not": {
+    "required": [
+      "change_budget"
+    ]
+  },
   "properties": {
-    "id": { "type": "string", "pattern": "^[A-Z]{2,6}-\\d{3,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"] },
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*-\\d+$",
+      "description": "Unique identifier for the change. Format: uppercase/digit PREFIX segments separated by dashes, final segment is one+ digits (e.g. CAWSFIX-16, P03-TRUTH-001, ALG-001A-HARDEN-01). Matches SPEC_ID_PATTERN in spec-validation.js (CAWSFIX-21 alignment)."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 10,
+      "maxLength": 200,
+      "description": "Clear, descriptive title"
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "feature",
+        "fix",
+        "refactor",
+        "chore",
+        "doc",
+        "docs"
+      ],
+      "description": "Type of work (informational; `mode` is the enforced gate input)"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "draft",
+        "active",
+        "in_progress",
+        "completed",
+        "closed",
+        "archived"
+      ]
+    },
+    "created_at": {
+      "type": "string"
+    },
+    "updated_at": {
+      "type": "string"
+    },
+    "worktree": {
+      "type": "string",
+      "description": "CAWS worktree name assigned to this spec"
+    },
+    "risk_tier": {
+      "type": [
+        "integer",
+        "string"
+      ],
+      "enum": [
+        1,
+        2,
+        3,
+        "1",
+        "2",
+        "3"
+      ],
+      "description": "Risk level (1=high, 2=medium, 3=low)"
+    },
+    "mode": {
+      "type": "string",
+      "enum": [
+        "feature",
+        "refactor",
+        "fix",
+        "doc",
+        "docs",
+        "chore",
+        "development"
+      ],
+      "description": "Mode of change. `development` is the default used by `caws specs create`; feature/refactor/fix/doc/chore are the classic modes the legacy validator accepted."
+    },
     "waiver_ids": {
       "type": "array",
-      "items": { "type": "string", "pattern": "^WV-\\d{4}$" },
+      "items": {
+        "type": "string",
+        "pattern": "^WV-\\d{4}$"
+      },
       "description": "IDs of active waivers applying to this spec"
     },
     "blast_radius": {
       "type": "object",
-      "required": ["modules"],
+      "required": [
+        "modules",
+        "data_migration"
+      ],
       "properties": {
-        "modules": { "type": "array", "items": { "type": "string" } },
-        "data_migration": { "type": "boolean" }
-      }
+        "modules": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "List of modules/paths the change touches"
+        },
+        "data_migration": {
+          "type": "boolean",
+          "description": "Whether the change requires a data migration"
+        }
+      },
+      "additionalProperties": true
+    },
+    "operational_rollback_slo": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Time target for operational rollback (e.g. '5m', '30m', '1h')"
     },
-    "operational_rollback_slo": { "type": "string" },
     "scope": {
       "type": "object",
-      "required": ["in", "out"],
+      "required": [
+        "in"
+      ],
       "properties": {
-        "in": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
-        "out": { "type": "array", "items": { "type": "string" } }
-      }
+        "in": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "description": "Files/paths allowed to be edited (non-empty)"
+        },
+        "out": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Files/paths explicitly excluded from edits"
+        }
+      },
+      "additionalProperties": true
+    },
+    "invariants": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1,
+      "description": "Properties that must hold across the change (non-empty)"
     },
-    "invariants": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
     "acceptance": {
       "type": "array",
       "minItems": 1,
+      "description": "Given/When/Then acceptance criteria (non-empty)",
       "items": {
         "type": "object",
-        "required": ["id", "given", "when", "then"],
+        "required": [
+          "id",
+          "given",
+          "when",
+          "then"
+        ],
         "properties": {
-          "id": { "type": "string", "pattern": "^A\\d+$" },
-          "given": { "type": "string" },
-          "when": { "type": "string" },
-          "then": { "type": "string" }
-        }
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "given": {
+            "type": "string",
+            "minLength": 1
+          },
+          "when": {
+            "type": "string",
+            "minLength": 1
+          },
+          "then": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": true
       }
     },
     "non_functional": {
       "type": "object",
+      "required": [
+        "a11y",
+        "perf",
+        "security"
+      ],
       "properties": {
-        "a11y": { "type": "array", "items": { "type": "string" } },
+        "a11y": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Accessibility requirements (may be empty array if not applicable)"
+        },
         "perf": {
           "type": "object",
-          "properties": {
-            "api_p95_ms": { "type": "integer", "minimum": 1 },
-            "lcp_ms": { "type": "integer", "minimum": 1 }
-          },
-          "additionalProperties": false
+          "description": "Performance requirements (e.g. api_p95_ms, lcp_ms)"
         },
-        "security": { "type": "array", "items": { "type": "string" } }
+        "security": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Security requirements (may be empty array if not applicable)"
+        }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "contracts": {
       "type": "array",
-      "minItems": 1,
+      "description": "API contracts. Empty array is permitted; CAWSFIX-06 will warn (not fail) when mode=feature with empty contracts.",
       "items": {
         "type": "object",
-        "required": ["type", "path"],
+        "required": [
+          "type",
+          "path"
+        ],
         "properties": {
-          "type": { "type": "string", "enum": ["openapi", "graphql", "proto", "pact"] },
-          "path": { "type": "string" }
-        }
+          "type": {
+            "type": "string",
+            "enum": [
+              "openapi",
+              "graphql",
+              "proto",
+              "pact",
+              "project_setup"
+            ]
+          },
+          "path": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": true
       }
     },
     "observability": {
+      "type": "object"
+    },
+    "migrations": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "rollback": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "experimental_mode": {
       "type": "object",
+      "required": [
+        "enabled",
+        "rationale",
+        "expires_at"
+      ],
       "properties": {
-        "logs": { "type": "array", "items": { "type": "string" } },
-        "metrics": { "type": "array", "items": { "type": "string" } },
-        "traces": { "type": "array", "items": { "type": "string" } }
+        "enabled": {
+          "type": "boolean"
+        },
+        "rationale": {
+          "type": "string"
+        },
+        "expires_at": {
+          "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"
+      "minimum": 1
     },
     "human_override": {
       "type": "object",
+      "required": [
+        "approved_by",
+        "reason"
+      ],
       "properties": {
-        "approved_by": { "type": "string" },
-        "reason": { "type": "string" },
+        "approved_by": {
+          "type": "string"
+        },
+        "reason": {
+          "type": "string"
+        },
         "waived_requirements": {
           "type": "array",
           "items": {
-            "type": "string",
-            "enum": ["mutation_testing", "contract_tests", "coverage", "manual_review"]
+            "type": "string"
           }
         },
-        "expiry_date": { "type": "string", "format": "date-time" }
-      },
-      "required": ["approved_by", "reason"]
+        "expiry_date": {
+          "type": "string"
+        }
+      }
     },
     "ai_assessment": {
       "type": "object",
       "properties": {
-        "confidence_level": { "type": "integer", "minimum": 1, "maximum": 10 },
-        "uncertainty_areas": { "type": "array", "items": { "type": "string" } },
-        "recommended_pairing": { "type": "boolean" }
+        "confidence_level": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10
+        },
+        "uncertainty_areas": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "recommended_pairing": {
+          "type": "boolean"
+        }
       }
     }
   },
-  "additionalProperties": false
+  "additionalProperties": true
 }

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

@@ -21,11 +21,13 @@
           "baseBranch": { "type": "string" },
           "scope": { "type": ["string", "null"] },
           "specId": { "type": ["string", "null"] },
+          "owner": { "type": ["string", "null"], "description": "CLAUDE_SESSION_ID of the creating agent" },
           "createdAt": { "type": "string", "format": "date-time" },
           "destroyedAt": { "type": "string", "format": "date-time" },
+          "autoRegistered": { "type": "boolean" },
           "status": {
             "type": "string",
-            "enum": ["active", "orphaned", "missing", "destroyed"]
+            "enum": ["fresh", "active", "merged", "orphaned", "missing", "stale-merged", "destroyed"]
           }
         },
         "additionalProperties": false

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

@@ -1,6 +1,13 @@
 id: '{{FEATURE_ID}}'
 title: '{{FEATURE_TITLE}}'
-risk_tier: { { TIER } }
+# Recommended when the spec belongs to a CAWS worktree:
+# worktree: '{{WORKTREE_NAME}}'
+risk_tier: {{TIER}}
+mode: feature
+blast_radius:
+  modules: []
+  data_migration: false
+operational_rollback_slo: "30m"
 scope:
   in:
     - '{{SCOPE_ITEM_1}}'
@@ -37,8 +44,8 @@ non_functional:
   a11y:
     - '{{ACCESSIBILITY_REQUIREMENT}}'
   perf:
-    api_p95_ms: { { PERF_BUDGET } }
-    lcp_ms: { { LCP_BUDGET } }
+    api_p95_ms: {{PERF_BUDGET}}
+    lcp_ms: {{LCP_BUDGET}}
   security:
     - '{{SECURITY_REQUIREMENT}}'
 contracts:
@@ -71,4 +78,3 @@ rollback:
 #   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/scope-guard.js

@@ -70,26 +70,71 @@ function checkFileScope(filePath, projectDir) {
     return { inScope: true, reason: 'js-yaml not available' };
   }
 
-  const specs = [];
+  // --- Authoritative spec detection ---
+  // If inside a worktree with a mutual spec binding, only check that spec.
+  let authoritativeSpec = null;
+  let mode = 'union';
 
-  if (fs.existsSync(specFile)) {
-    try {
-      const s = yaml.load(fs.readFileSync(specFile, 'utf8'));
-      if (s && !TERMINAL.has(s.status)) {
-        specs.push({ source: 'working-spec', spec: s });
-      }
-    } catch (_) {}
+  const registryPath = path.join(projectDir, '.caws', 'worktrees.json');
+  const worktreesBase = path.join(projectDir, '.caws', 'worktrees');
+  const cwd = process.cwd();
+
+  if (cwd.startsWith(worktreesBase + path.sep)) {
+    const relative = path.relative(worktreesBase, cwd);
+    const worktreeName = relative.split(path.sep)[0];
+
+    if (worktreeName && fs.existsSync(registryPath)) {
+      try {
+        const reg = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+        const entry = reg.worktrees && reg.worktrees[worktreeName];
+
+        if (entry && entry.specId) {
+          const specCandidates = [
+            path.join(specsDir, entry.specId + '.yaml'),
+            path.join(specsDir, entry.specId + '.yml'),
+          ];
+          for (const candidate of specCandidates) {
+            if (fs.existsSync(candidate)) {
+              try {
+                const s = yaml.load(fs.readFileSync(candidate, 'utf8'));
+                if (s && !TERMINAL.has(s.status) && s.worktree === worktreeName) {
+                  authoritativeSpec = { source: path.basename(candidate), spec: s };
+                  mode = 'authoritative';
+                }
+              } catch (_) {}
+              break;
+            }
+          }
+        }
+      } catch (_) {}
+    }
   }
 
-  if (fs.existsSync(specsDir)) {
-    for (const f of fs.readdirSync(specsDir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))) {
+  // --- Collect specs based on mode ---
+  const specs = [];
+
+  if (authoritativeSpec) {
+    specs.push(authoritativeSpec);
+  } else {
+    if (fs.existsSync(specFile)) {
       try {
-        const s = yaml.load(fs.readFileSync(path.join(specsDir, f), 'utf8'));
+        const s = yaml.load(fs.readFileSync(specFile, 'utf8'));
         if (s && !TERMINAL.has(s.status)) {
-          specs.push({ source: f, spec: s });
+          specs.push({ source: 'working-spec', spec: s });
         }
       } catch (_) {}
     }
+
+    if (fs.existsSync(specsDir)) {
+      for (const f of fs.readdirSync(specsDir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))) {
+        try {
+          const s = yaml.load(fs.readFileSync(path.join(specsDir, f), 'utf8'));
+          if (s && !TERMINAL.has(s.status)) {
+            specs.push({ source: f, spec: s });
+          }
+        } catch (_) {}
+      }
+    }
   }
 
   if (specs.length === 0) {
@@ -100,17 +145,23 @@ function checkFileScope(filePath, projectDir) {
   for (const { source, spec } of specs) {
     for (const pattern of (spec.scope?.out || [])) {
       if (globToRegex(pattern).test(filePath)) {
-        return { inScope: false, reason: `out-of-scope in ${source} (pattern: ${pattern})` };
+        const modeHint = mode === 'union'
+          ? '. No authoritative spec bound — checking all active specs. Fix: caws worktree bind <spec-id>'
+          : '';
+        return { inScope: false, reason: `out-of-scope in ${source} (pattern: ${pattern})${modeHint}` };
       }
     }
   }
 
-  // Union all scope.in — must match at least one
+  // scope.in — must match at least one
   const allIn = specs.flatMap(({ spec }) => spec.scope?.in || []);
   if (allIn.length > 0) {
     const found = allIn.some(pattern => globToRegex(pattern).test(filePath));
     if (!found) {
-      return { inScope: false, reason: 'not in any active spec scope.in' };
+      const modeHint = mode === 'union'
+        ? '. No authoritative spec bound — checking all active specs. Fix: caws worktree bind <spec-id>'
+        : '';
+      return { inScope: false, reason: `not in any active spec scope.in${modeHint}` };
     }
   }
 

package/templates/.claude/README.md

@@ -38,7 +38,7 @@ Run before Claude executes a tool:
 |------|---------|---------|
 | `block-dangerous.sh` | `Bash` | Block destructive shell commands |
 | `scan-secrets.sh` | `Read` | Warn when reading sensitive files |
-| `scope-guard.sh` | `Write\|Edit` | Check scope boundaries before edits |
+| `scope-guard.sh` | `Write\|Edit` | Check scope boundaries before edits (use `caws scope show` to diagnose blocks) |
 
 ### PostToolUse Hooks
 

package/templates/.claude/hooks/block-dangerous.sh

@@ -1,23 +1,70 @@
 #!/bin/bash
-# CAWS Dangerous Command Blocker for Claude Code
-# Blocks potentially destructive shell commands
+# CAWS Command Safety Gate for Claude Code
+# Delegates to classify_command.py for robust command parsing and classification.
+# Falls back to bash pattern matching if Python is unavailable.
+#
+# The Python classifier handles:
+#   - Heredoc-aware parsing (won't false-positive on quoted dangerous commands)
+#   - Quoted-region stripping (echo "git reset --hard" is safe)
+#   - Pipeline-aware dangers (curl | sh)
+#   - Context-aware rm classification (safe prefixes vs dangerous targets)
+#   - Proper shell segmentation (&&, ||, ;, |)
+#
 # @author @darianrosebrook
 
 set -euo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
 # Read JSON input from Claude Code
 INPUT=$(cat)
 
 # Extract tool info
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
-COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""')
+COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // ""')
 
 # Only check Bash tool
 if [[ "$TOOL_NAME" != "Bash" ]] || [[ -z "$COMMAND" ]]; then
   exit 0
 fi
 
-# Dangerous command patterns
+# --- Try Python classifier first (preferred) ---
+CLASSIFIER="$SCRIPT_DIR/classify_command.py"
+if [[ -f "$CLASSIFIER" ]] && command -v python3 >/dev/null 2>&1; then
+  REPO_ROOT="${CLAUDE_PROJECT_DIR:-.}"
+  CLASSIFIER_STDERR=$(mktemp)
+  RESULT=$(printf '%s' "$COMMAND" | python3 "$CLASSIFIER" \
+    --repo-root "$REPO_ROOT" \
+    --home "$HOME" \
+    --cwd "$(pwd)" 2>"$CLASSIFIER_STDERR") || {
+    DIAG=$(head -c 200 "$CLASSIFIER_STDERR" 2>/dev/null || true)
+    rm -f "$CLASSIFIER_STDERR"
+    RESULT="{\"decision\":\"ask\",\"reason\":\"command classifier failed: ${DIAG:-unknown error}\"}"
+  }
+  rm -f "$CLASSIFIER_STDERR"
+
+  DECISION=$(printf '%s' "$RESULT" | jq -r '.decision // "ask"')
+  REASON=$(printf '%s' "$RESULT" | jq -r '.reason // "unknown"')
+
+  case "$DECISION" in
+    allow)
+      exit 0
+      ;;
+    deny)
+      echo "BLOCKED: $REASON" >&2
+      echo "Command was: $COMMAND" >&2
+      exit 2
+      ;;
+    ask)
+      echo "WARNING: $REASON" >&2
+      echo "Command was: $COMMAND" >&2
+      exit 1
+      ;;
+  esac
+fi
+
+# --- Fallback: bash pattern matching (less precise, no heredoc/quote awareness) ---
+
 DANGEROUS_PATTERNS=(
   # Destructive file operations
   'rm -rf /'
@@ -96,7 +143,6 @@ for pattern in "${DANGEROUS_PATTERNS[@]}"; do
     # Allow git rebase/cherry-pick only when no worktrees are active
     if [[ "$pattern" == *"git rebase"* ]] || [[ "$pattern" == *"git cherry-pick"* ]]; then
       PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
-      # Resolve to main repo root if we're in a worktree
       if command -v git >/dev/null 2>&1; then
         GIT_COMMON=$(cd "$PROJECT_DIR" && git rev-parse --git-common-dir 2>/dev/null || echo "")
         if [[ -n "$GIT_COMMON" ]] && [[ "$GIT_COMMON" != ".git" ]]; then
@@ -116,7 +162,6 @@ for pattern in "${DANGEROUS_PATTERNS[@]}"; do
           } catch(e) { console.log(0); }
         " 2>/dev/null || echo "0")
         if [[ "$ACTIVE_COUNT" -gt 0 ]]; then
-          # Extract the specific git subcommand for the message
           GIT_SUBCMD="git operation"
           [[ "$pattern" == *"git rebase"* ]] && GIT_SUBCMD="git rebase"
           [[ "$pattern" == *"git cherry-pick"* ]] && GIT_SUBCMD="git cherry-pick"
@@ -126,7 +171,6 @@ for pattern in "${DANGEROUS_PATTERNS[@]}"; do
           exit 2
         fi
       fi
-      # No active worktrees — allow
       continue
     fi
 
@@ -142,11 +186,8 @@ for pattern in "${DANGEROUS_PATTERNS[@]}"; do
       fi
     fi
 
-    # Output to stderr for Claude to see
     echo "BLOCKED: Command matches dangerous pattern: $pattern" >&2
     echo "Command was: $COMMAND" >&2
-
-    # Exit code 2 blocks the tool and shows stderr to Claude
     exit 2
   fi
 done