@paths.design/caws-cli 10.0.1 → 10.2.0

package/dist/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,79 +15,178 @@
     "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 },
-    "type": { "type": "string", "enum": ["feature", "fix", "refactor", "chore", "docs"] },
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*-\\d+[a-z]*$",
+      "description": "Unique identifier for the change. Format: uppercase/digit PREFIX segments separated by dashes, final segment is one+ digits with an optional lowercase suffix (e.g. CAWSFIX-16, P03-TRUTH-001, ALG-001A-HARDEN-01, APC-01a). Matches SPEC_ID_PATTERN in spec-validation.js (CAWSFIX-25 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"]
+      "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."
     },
-    "created_at": { "type": "string" },
-    "updated_at": { "type": "string" },
-    "risk_tier": { "type": ["integer", "string"], "enum": [1, 2, 3, "1", "2", "3"] },
-    "mode": { "type": "string", "enum": ["feature", "refactor", "fix", "doc", "docs", "chore", "development"] },
     "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 },
-    "acceptance": {
+    "invariants": {
       "type": "array",
-      "minItems": 0,
       "items": {
-        "type": "object",
-        "required": ["id", "given", "when", "then"],
-        "properties": {
-          "id": { "type": "string", "pattern": "^A\\d+$" },
-          "given": { "type": "string" },
-          "when": { "type": "string" },
-          "then": { "type": "string" }
-        }
-      }
+        "type": "string"
+      },
+      "minItems": 1,
+      "description": "Properties that must hold across the change (non-empty)"
     },
-    "acceptance_criteria": {
+    "acceptance": {
       "type": "array",
-      "minItems": 0,
+      "minItems": 1,
+      "description": "Given/When/Then acceptance criteria (non-empty)",
       "items": {
         "type": "object",
-        "required": ["id"],
+        "required": [
+          "id",
+          "given",
+          "when",
+          "then"
+        ],
         "properties": {
-          "id": { "type": "string" },
-          "description": { "type": "string" },
-          "completed": { "type": "boolean" },
-          "test": { "type": "string" },
-          "test_command": { "type": "string" },
-          "test_nodeids": {
-            "type": "array",
-            "items": { "type": "string" }
+          "id": {
+            "type": "string",
+            "minLength": 1
           },
-          "evidence": {
-            "oneOf": [
-              { "type": "string" },
-              {
-                "type": "array",
-                "items": { "type": "string" }
-              }
-            ]
+          "given": {
+            "type": "string",
+            "minLength": 1
+          },
+          "when": {
+            "type": "string",
+            "minLength": 1
+          },
+          "then": {
+            "type": "string",
+            "minLength": 1
           }
         },
         "additionalProperties": true
@@ -95,82 +194,147 @@
     },
     "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",
+      "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", "project_setup"] },
-          "path": { "type": "string" },
-          "description": { "type": "string" },
-          "version": { "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",
-      "properties": {
-        "logs": { "type": "array", "items": { "type": "string" } },
-        "metrics": { "type": "array", "items": { "type": "string" } },
-        "traces": { "type": "array", "items": { "type": "string" } }
+      "type": "object"
+    },
+    "migrations": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "rollback": {
+      "type": "array",
+      "items": {
+        "type": "string"
       }
     },
-    "migrations": { "type": "array", "items": { "type": "string" } },
-    "rollback": { "type": "array", "items": { "type": "string" } },
     "experimental_mode": {
       "type": "object",
-      "description": "Enables experimental mode with reduced requirements",
-      "required": ["enabled", "rationale", "expires_at"],
+      "required": [
+        "enabled",
+        "rationale",
+        "expires_at"
+      ],
       "properties": {
-        "enabled": { "type": "boolean" },
-        "rationale": { "type": "string" },
-        "expires_at": { "type": "string" }
+        "enabled": {
+          "type": "boolean"
+        },
+        "rationale": {
+          "type": "string"
+        },
+        "expires_at": {
+          "type": "string"
+        }
       }
     },
     "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/dist/templates/.caws/templates/working-spec.template.yml

@@ -1,9 +1,12 @@
 id: '{{FEATURE_ID}}'
 title: '{{FEATURE_TITLE}}'
+# 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:
@@ -75,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/dist/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/dist/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/dist/templates/.claude/hooks/protected-paths.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# CAWS Protected Paths Guard for Claude Code
+# Blocks direct Write/Edit access to guard code and guard state.
+# @author @darianrosebrook
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+case "$TOOL_NAME" in
+  Write|Edit) ;;
+  *) exit 0 ;;
+esac
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# If you are reading this because a write was blocked, do not edit hook files or
+# strike-state files to bypass a guard. Switch into the correct worktree, fix the
+# active spec scope, or ask the user if the guard itself is wrong.
+case "$FILE_PATH" in
+  */.claude/hooks/*)
+    echo "BLOCKED: $FILE_PATH is protected." >&2
+    echo "Ask the user for permission before editing Claude hook scripts." >&2
+    exit 1
+    ;;
+  */.claude/logs/guard-strikes-*.json)
+    echo "BLOCKED: $FILE_PATH is protected guard state." >&2
+    echo "Do not reset or edit strike counters to bypass enforcement." >&2
+    echo "Switch into the correct worktree, update the active CAWS spec scope, or ask the user for direction instead." >&2
+    exit 2
+    ;;
+esac
+
+exit 0