@paths.design/caws-cli 10.0.1 → 10.1.0

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

package/dist/templates/.claude/hooks/scope-guard.sh

@@ -204,31 +204,83 @@ if command -v node >/dev/null 2>&1; then
         process.exit(0);
       }
 
-      // Collect all active specs (working-spec + feature specs)
-      const specs = [];
+      const projectDir = '$PROJECT_DIR';
 
-      // Load working-spec.yaml if present
-      const mainSpec = '$SPEC_FILE';
-      if (fs.existsSync(mainSpec)) {
-        try {
-          const s = yaml.load(fs.readFileSync(mainSpec, 'utf8'));
-          if (s && !TERMINAL.has(s.status)) {
-            specs.push({ source: 'working-spec', spec: s });
-          }
-        } catch (_) {}
+      // --- Authoritative spec detection ---
+      // If we are inside a worktree with a bound specId, ONLY check that spec.
+      // This prevents unrelated specs from blocking writes via broad scope.out.
+      let authoritativeSpec = null;
+      let mode = 'union';
+
+      const registryPath = path.join(projectDir, '.caws', 'worktrees.json');
+      const cwd = process.cwd();
+      const worktreesBase = path.join(projectDir, '.caws', 'worktrees');
+
+      if (cwd.startsWith(worktreesBase + '/')) {
+        const relative = cwd.slice(worktreesBase.length + 1);
+        const worktreeName = relative.split('/')[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) {
+              // Try to load the bound spec
+              const specsDir = '$SPECS_DIR';
+              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)) {
+                      // Verify mutual binding: spec must also reference this worktree
+                      if (s.worktree === worktreeName) {
+                        authoritativeSpec = { source: path.basename(candidate), spec: s };
+                        mode = 'authoritative';
+                      }
+                    }
+                  } catch (_) {}
+                  break;
+                }
+              }
+            }
+          } catch (_) {}
+        }
       }
 
-      // Load feature specs from .caws/specs/
-      const specsDir = '$SPECS_DIR';
-      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) {
+        // Authoritative: only the bound spec matters
+        specs.push(authoritativeSpec);
+      } else {
+        // Union: load all active specs
+        const mainSpec = '$SPEC_FILE';
+        if (fs.existsSync(mainSpec)) {
           try {
-            const s = yaml.load(fs.readFileSync(path.join(specsDir, f), 'utf8'));
+            const s = yaml.load(fs.readFileSync(mainSpec, 'utf8'));
             if (s && !TERMINAL.has(s.status)) {
-              specs.push({ source: f, spec: s });
+              specs.push({ source: 'working-spec', spec: s });
             }
           } catch (_) {}
         }
+
+        const specsDir = '$SPECS_DIR';
+        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 (_) {}
+          }
+        }
       }
 
       // No active specs — allow everything
@@ -237,18 +289,18 @@ if command -v node >/dev/null 2>&1; then
         process.exit(0);
       }
 
-      // Check scope.out across ALL active specs — any match blocks
+      // Check scope.out — any match blocks
       for (const { source, spec } of specs) {
         for (const pattern of (spec.scope?.out || [])) {
           const regex = globToRegex(pattern);
           if (regex.test(filePath)) {
-            console.log('out_of_scope:' + source + ':' + pattern);
+            console.log('out_of_scope:' + mode + ':' + source + ':' + pattern);
             process.exit(0);
           }
         }
       }
 
-      // Union all scope.in patterns — file must match at least one
+      // scope.in — file must match at least one pattern
       const allInScope = specs.flatMap(({ spec }) => spec.scope?.in || []);
       if (allInScope.length > 0) {
         let found = false;
@@ -260,7 +312,7 @@ if command -v node >/dev/null 2>&1; then
           }
         }
         if (!found) {
-          console.log('not_in_scope');
+          console.log('not_in_scope:' + mode);
           process.exit(0);
         }
       }
@@ -282,18 +334,45 @@ if command -v node >/dev/null 2>&1; then
 
   if [[ "$SCOPE_CHECK" == out_of_scope:* ]]; then
     DETAIL="${SCOPE_CHECK#out_of_scope:}"
-    SOURCE="${DETAIL%%:*}"
-    PATTERN="${DETAIL#*:}"
+    # Format: mode:source:pattern
+    MODE="${DETAIL%%:*}"
+    REST="${DETAIL#*:}"
+    SOURCE="${REST%%:*}"
+    PATTERN="${REST#*:}"
     echo "BLOCKED: $REL_PATH is excluded by scope.out in $SOURCE (pattern: $PATTERN)"
-    echo "  Scope allows: files not matching scope.out patterns"
-    echo "  To modify scope, update the spec's scope.out field"
+    if [[ "$MODE" == "union" ]]; then
+      echo "  Mode: union (no authoritative spec bound to this worktree)"
+      echo "  The scope guard is checking ALL active specs because the worktree<->spec"
+      echo "  binding is missing. An unrelated spec may be blocking this edit."
+      echo "  Fix: caws worktree bind <your-spec-id>"
+      echo "  Diagnose: caws scope show"
+    else
+      echo "  Mode: authoritative (checking only your bound spec)"
+      echo "  To modify scope, update the spec's scope.out field"
+    fi
+    exit 2
+  fi
+
+  if [[ "$SCOPE_CHECK" == not_in_scope:* ]]; then
+    MODE="${SCOPE_CHECK#not_in_scope:}"
+    echo "BLOCKED: $REL_PATH is not in the defined scope.in of any active spec"
+    if [[ "$MODE" == "union" ]]; then
+      echo "  Mode: union (no authoritative spec bound to this worktree)"
+      echo "  The scope guard is checking ALL active specs because the worktree<->spec"
+      echo "  binding is missing. Your file may be in a scope that no spec covers."
+      echo "  Fix: caws worktree bind <your-spec-id>"
+      echo "  Diagnose: caws scope show"
+    else
+      echo "  Mode: authoritative (checking only your bound spec)"
+      echo "  To modify scope, update the spec's scope.in field"
+    fi
     exit 2
   fi
 
+  # Legacy fallback for unqualified not_in_scope (shouldn't happen with updated logic)
   if [[ "$SCOPE_CHECK" == "not_in_scope" ]]; then
     echo "BLOCKED: $REL_PATH is not in the defined scope.in of any active spec"
-    echo "  Scope allows: files matching scope.in patterns in active specs"
-    echo "  To modify scope, update the spec's scope.in field"
+    echo "  Diagnose: caws scope show"
     exit 2
   fi
 fi

package/dist/templates/.claude/hooks/worktree-write-guard.sh

@@ -66,14 +66,107 @@ if [[ "$WT_COUNT" -le 0 ]] 2>/dev/null; then
   exit 0
 fi
 
-# Allow edits to configuration and documentation (benign, no merge conflict risk)
+# Main is blocked during active worktree work because shared unstaged state makes
+# agents stash, checkpoint, or explain each other's edits. Keep direct main edits
+# limited to coordination/docs/scratch paths, then use active spec scope below to
+# permit only files no worktree claims.
 if [[ -n "$FILE_PATH" ]]; then
   case "$FILE_PATH" in
-    */.claude/*|*/.caws/*) exit 0 ;;
-    */docs/*) exit 0 ;;
+    .caws/*|*/.caws/*) exit 0 ;;
+    .claude/*|*/.claude/*) exit 0 ;;
+    .gitignore|*/.gitignore) exit 0 ;;
+    .tmp/*|*/.tmp/*) exit 0 ;;
+    tmp/*|*/tmp/*) exit 0 ;;
+    .archive/*|*/.archive/*) exit 0 ;;
+    .githooks/*|*/.githooks/*) exit 0 ;;
+    .github/*|*/.github/*) exit 0 ;;
+    docs/*|*/docs/*) exit 0 ;;
   esac
 fi
 
+if [[ -n "$FILE_PATH" ]]; then
+  REL_PATH="$FILE_PATH"
+  if [[ "$FILE_PATH" == "$PROJECT_DIR"/* ]]; then
+    REL_PATH="${FILE_PATH#$PROJECT_DIR/}"
+  fi
+
+  SPEC_CONTENTION_CHECK=$(PROJECT_DIR="$PROJECT_DIR" CURRENT_BRANCH="$CURRENT_BRANCH" REL_PATH="$REL_PATH" node -e "
+    var fs = require('fs');
+    var path = require('path');
+    var yaml;
+
+    try {
+      yaml = require('js-yaml');
+    } catch (_) {
+      console.log('unknown:no-js-yaml');
+      process.exit(0);
+    }
+
+    function globToRegExp(pattern) {
+      return new RegExp(String(pattern).replace(/\\*/g, '.*').replace(/\\?/g, '.'));
+    }
+
+    try {
+      var projectDir = process.env.PROJECT_DIR;
+      var currentBranch = process.env.CURRENT_BRANCH;
+      var relPath = process.env.REL_PATH;
+      var registryPath = path.join(projectDir, '.caws', 'worktrees.json');
+      var registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+      var worktrees = Object.values(registry.worktrees || {}).filter(function(w) {
+        return (w.status === 'active' || w.status === 'fresh' || w.status === 'merged') && w.baseBranch === currentBranch;
+      });
+
+      if (worktrees.length === 0) {
+        console.log('unknown:no-registry-worktrees');
+        process.exit(0);
+      }
+
+      for (var wi = 0; wi < worktrees.length; wi++) {
+        var wt = worktrees[wi];
+        if (!wt.specId) {
+          console.log('unknown:missing-specId:' + (wt.name || 'unnamed'));
+          process.exit(0);
+        }
+
+        var specPath = path.join(projectDir, '.caws', 'specs', wt.specId + '.yaml');
+        if (!fs.existsSync(specPath)) {
+          specPath = path.join(projectDir, '.caws', 'specs', wt.specId + '.yml');
+        }
+        if (!fs.existsSync(specPath)) {
+          console.log('unknown:missing-spec:' + wt.specId);
+          process.exit(0);
+        }
+
+        var spec = yaml.load(fs.readFileSync(specPath, 'utf8')) || {};
+        var scope = spec.scope || {};
+        var patterns = []
+          .concat(Array.isArray(scope.in) ? scope.in : [])
+          .concat(Array.isArray(scope.out) ? scope.out : []);
+
+        if (patterns.length === 0) {
+          console.log('unknown:missing-scope:' + wt.specId);
+          process.exit(0);
+        }
+
+        for (var pi = 0; pi < patterns.length; pi++) {
+          if (globToRegExp(patterns[pi]).test(relPath)) {
+            console.log('claimed:' + (wt.name || wt.specId) + ':' + patterns[pi]);
+            process.exit(0);
+          }
+        }
+      }
+
+      console.log('clear');
+    } catch (error) {
+      console.log('unknown:' + error.message);
+    }
+  " 2>/dev/null || echo "unknown:node-error")
+
+  if [[ "$SPEC_CONTENTION_CHECK" == "clear" ]]; then
+    exit 0
+  fi
+fi
+
 # Allow edits during an active merge (conflict resolution).
 # The worktree-isolation rules explicitly permit merge commits on the base branch.
 # Conflict resolution requires Write/Edit on the conflicted files.

package/dist/templates/.claude/settings.json

@@ -29,6 +29,11 @@
       {
         "matcher": "Write|Edit",
         "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protected-paths.sh",
+            "timeout": 5
+          },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/worktree-write-guard.sh",

package/dist/templates/CLAUDE.md

@@ -29,6 +29,9 @@ Before writing code, check the canonical spec for the current feature:
 # Create a feature spec for isolated work
 caws specs create FEAT-001 --type feature --title "description"
 
+# If you're in a CAWS worktree, the created spec should record it:
+# worktree: <worktree-name>
+
 # Validate the feature spec
 caws validate --spec-id FEAT-001
 
@@ -68,6 +71,7 @@ Canonical feature specs live at `.caws/specs/<ID>.yaml` (create with `caws specs
 
 - **Risk tier**: Quality requirements (T1: critical, T2: standard, T3: low risk)
 - **Mode**: The type of change (`feature`, `refactor`, `fix`, `doc`, `chore`) -- required
+- **Worktree**: The owning CAWS worktree name for this spec (`worktree`) -- recommended for all isolated work
 - **Blast radius**: Which modules are affected (`blast_radius.modules`) -- required
 - **Operational rollback SLO**: Time target for rollback (e.g. `"30m"`) -- required
 - **Scope**: Which files you can edit (`scope.in`) and which are off-limits (`scope.out`)
@@ -76,6 +80,36 @@ Canonical feature specs live at `.caws/specs/<ID>.yaml` (create with `caws specs
 
 Always stay within scope boundaries and change budgets.
 
+Recommended operating rule: one active feature spec, one active worktree. If a task has a worktree, record that ownership in the spec YAML with `worktree: <name>`.
+
+### Scope and Worktree Binding
+
+The scope guard enforces file edit boundaries based on your spec's `scope.in` and `scope.out` patterns. **How it enforces depends on whether your worktree is bound to a spec:**
+
+- **Authoritative mode** (worktree bound to a spec): Only your spec's scope patterns are checked. Other agents' specs cannot block your edits. This is the correct state.
+- **Union mode** (no binding): The guard checks ALL active specs. Any `scope.out` from any spec can block you, even unrelated ones. This is the common source of "why is spec X blocking me?" confusion.
+
+**The mutual binding** requires both sides:
+1. The worktree registry (`.caws/worktrees.json`) must have `specId` pointing to your spec
+2. Your spec (`.caws/specs/<id>.yaml`) must have `worktree: <name>` pointing to your worktree
+
+If either side is missing, the guard falls back to union mode.
+
+**Quick commands:**
+```bash
+# See your effective scope and binding health
+caws scope show
+
+# Fix a broken binding
+caws worktree bind <spec-id>
+```
+
+**Recovery checklist** (when the scope guard blocks you unexpectedly):
+1. Run `caws scope show` — check if you're in authoritative or union mode
+2. If union mode: bind your spec with `caws worktree bind <spec-id>`
+3. If authoritative but still blocked: the file is genuinely outside your spec's scope. Update your spec's `scope.in` if the file should be in scope, or request a waiver
+4. Do NOT modify another spec's `scope.out` to unblock yourself — that defeats the isolation
+
 > **Budget note**: `change_budget:` in a spec is informational documentation only. CAWS
 > derives the enforced budget from `policy.yaml` keyed on `risk_tier`. The field in the
 > spec is not used by `caws validate` for enforcement.

package/dist/templates/agents.md

@@ -38,6 +38,27 @@ caws specs create my-feature --type feature --title "My Feature"
 caws validate --spec-id my-feature
 ```
 
+## Scope and Worktree Binding
+
+The scope guard enforces `scope.in` and `scope.out` from your spec. How it enforces depends on binding:
+
+- **Authoritative mode** (worktree bound to a spec): Only your spec's scope is checked. Other agents' specs cannot block you.
+- **Union mode** (no binding): ALL active specs are checked. Any `scope.out` from any spec can block you.
+
+```bash
+# See your effective scope and binding health
+caws scope show
+
+# Fix a broken binding
+caws worktree bind <spec-id>
+```
+
+**Recovery** (when blocked unexpectedly):
+1. Run `caws scope show` to check mode and binding health
+2. If union mode: `caws worktree bind <spec-id>`
+3. If authoritative but blocked: update your spec's `scope.in`
+4. Do NOT edit another spec's `scope.out` to unblock yourself
+
 ## Key Rules
 
 1. **Stay in scope** -- only edit files listed in `scope.in`, never touch `scope.out`