@paths.design/caws-cli 10.0.1 → 10.2.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/rules/worktree-isolation.md

@@ -10,9 +10,27 @@ When multiple agents are working on this project, each agent MUST work in its ow
 ## Before starting work
 
 1. Check if worktrees exist: `caws worktree list` shows all active worktrees with last commit time and owner
-2. If worktrees are active and you are on the base branch, switch to your assigned worktree
-3. If no worktree exists for you, create one with `caws worktree create <name>` or `caws parallel setup <plan-file>`
-4. **Never touch a worktree you did not create.** Do not destroy, prune, stash, or "clean up" another agent's worktree — even if it looks stale. Another agent may be actively working in it. If you think a worktree is abandoned, leave it alone and let the user decide.
+2. Check who's actually working: `caws agents list` shows registered sessions and their bound worktree/spec, formatted as `<sessionId>:<platform>`
+3. If you're inside a worktree, run `caws status` — the Claim panel shows the current owner, last heartbeat, and any session-log path under `tmp/<sessionId>/`
+4. If worktrees are active and you are on the base branch, switch to your assigned worktree
+5. If no worktree exists for you, create one with `caws worktree create <name>` or `caws parallel setup <plan-file>`
+6. **Never touch a worktree you did not create.** Do not destroy, prune, stash, or "clean up" another agent's worktree — even if it looks stale. Another agent may be actively working in it. If you think a worktree is abandoned, leave it alone and let the user decide.
+
+## Foreign-claim soft-block
+
+`caws worktree bind`, `merge`, and `claim` refuse to mutate a worktree whose `worktrees.json:owner` is a session id different from the current session — unless `--takeover` is supplied. The refusal prints a structured warning naming the claimer, the heartbeat age, any session-log pointer under `tmp/<sessionId>/`, and the exact `--takeover` command:
+
+```
+Worktree 'wt-foo' is claimed by 8be65780-...:claude-code
+   Last heartbeat: 2026-04-27T17:04:00Z (23 min ago)
+   Session log:    tmp/8be65780-72e0-4fc7-a989-4ebac148c18d
+                   15 turns, last turn 2026-04-27T17:26:49Z
+   To proceed:     caws worktree claim wt-foo --takeover
+```
+
+**Decision-gating uses session-id equality only.** A stale heartbeat is NOT authorization to take over — paused sessions are not ended sessions. Read the session log under `tmp/<sessionId>/` for context first. Take over only when you have explicit user authorization.
+
+`--takeover` writes a durable `prior_owners` audit on the worktree entry (sessionId, platform, lastSeen-at-takeover, takenOver_at) so the handoff is traceable in `worktrees.json`, not just in agent memory.
 
 ## Forbidden operations when worktrees are active
 

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,58 @@ 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>
+
+# Inspect the agent registry — who is currently working what
+caws agents list
+
+# Inspect a specific worktree's claim (read-only by default)
+caws worktree claim <name>
+```
+
+**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
+
+### Agent Claims & Multi-Agent Coordination
+
+Each session gets registered in `.caws/agents.json` automatically (via the session-log hook and on every CAWS lifecycle CLI invocation). Worktree session ownership is tracked in `.caws/worktrees.json:owner` as a session id.
+
+`caws worktree bind`, `merge`, and `claim` will refuse to mutate a worktree owned by a different session id without explicit `--takeover`. The refusal prints a structured warning naming the claimer as `<sessionId>:<platform>`, the heartbeat age, and any matching `tmp/<sessionId>/` session-log path so you can read context before deciding.
+
+**Decision-gating uses session-id equality only.** TTL pruning of `agents.json` is registry hygiene; it does NOT authorize takeover. A stale heartbeat doesn't mean the prior session is dead — it may be paused.
+
+`--takeover` writes a durable `prior_owners` audit on the worktree entry (sessionId, platform, lastSeen-at-takeover, takenOver_at) so handoffs are traceable in `worktrees.json`, not just in agent memory.
+
+### Spec lifecycle: archive
+
+Use `caws specs archive <id>` to move a closed spec to the canonical `.caws/specs/.archive/` directory. The directory is filesystem-authoritative — `caws specs list` reports any file under `.archive/` as `status: archived` regardless of the YAML literal. This means manually-moved legacy specs (no registry entry) are correctly classified.
+
+If you try to `caws specs create <id>` for an id that already exists in `.archive/`, the command refuses without `--force`. With `--force`, the archived YAML is removed and a fresh draft is created — useful for resurrecting an old id with new intent.
+
 > **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,53 @@ 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
+
+## Multi-Agent Claims
+
+Each session is registered in `.caws/agents.json` automatically. Worktree session ownership is recorded in `.caws/worktrees.json:owner` as a session id. `caws worktree bind`, `merge`, and `claim` will refuse to mutate a worktree owned by a different session id without `--takeover`.
+
+```bash
+# See registered agents (composite <sessionId>:<platform> format)
+caws agents list
+
+# Inspect a worktree's claim — read-only by default
+caws worktree claim <name>
+
+# Take over a foreign claim (writes prior_owners audit)
+caws worktree claim <name> --takeover
+```
+
+When a refusal fires, the warning includes the claimer's session id, heartbeat age, and a pointer to any `tmp/<sessionId>/` session-log directory — read that log for context before deciding to take over. A stale heartbeat does NOT mean the prior session is dead; it may be paused.
+
+## Spec Lifecycle: Archive
+
+```bash
+# Move a closed spec to the canonical archive
+caws specs archive <spec-id>
+```
+
+The `.caws/specs/.archive/` directory is filesystem-authoritative — `caws specs list` reports any file under it as `archived` regardless of YAML status. `caws specs create` refuses ids that collide with archived files unless `--force` is supplied (which removes the archived copy and writes a fresh draft).
+
 ## Key Rules
 
 1. **Stay in scope** -- only edit files listed in `scope.in`, never touch `scope.out`