@paths.design/caws-cli 8.3.0 → 9.0.0

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

@@ -0,0 +1,207 @@
+#!/bin/bash
+# CAWS Worktree Safety Guard for Claude Code
+# Blocks dangerous operations when parallel worktrees are active
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# 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 // ""')
+
+# Only check Bash tool
+if [[ "$TOOL_NAME" != "Bash" ]] || [[ -z "$COMMAND" ]]; then
+  exit 0
+fi
+
+# --- Resolve main repo root ---
+# When running inside a worktree, CLAUDE_PROJECT_DIR points to the
+# worktree directory, but .caws/worktrees.json only exists in the main
+# repo. Use git's common dir to find the true repo root.
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+
+if command -v git >/dev/null 2>&1; then
+  GIT_COMMON_DIR=$(cd "$PROJECT_DIR" && git rev-parse --git-common-dir 2>/dev/null || echo "")
+  if [[ -n "$GIT_COMMON_DIR" ]] && [[ "$GIT_COMMON_DIR" != ".git" ]]; then
+    # Inside a worktree: --git-common-dir returns the main repo's .git path
+    # (e.g., /path/to/repo/.git or /path/to/repo/.git/worktrees/<name>/..)
+    CANDIDATE=$(cd "$PROJECT_DIR" && cd "$GIT_COMMON_DIR/.." 2>/dev/null && pwd || echo "")
+    if [[ -n "$CANDIDATE" ]] && [[ -d "$CANDIDATE/.caws" ]]; then
+      PROJECT_DIR="$CANDIDATE"
+    fi
+  fi
+fi
+
+# --- Gap 2: Block sparse checkout before the git-only filter ---
+# This must run before the "only check git commands" early-exit
+if echo "$COMMAND" | grep -qE 'caws\s+(worktree\s+create|parallel\s+setup).*--scope'; then
+  echo "BLOCKED: --scope (sparse checkout) is not allowed." >&2
+  echo "Sparse checkout breaks cross-module imports in most projects." >&2
+  echo "Use full worktrees without --scope. Scope enforcement comes from" >&2
+  echo "CAWS feature specs and lane discipline, not from hiding files." >&2
+  exit 2
+fi
+
+# --- Gap 5: Block cross-boundary file copies ---
+WORKTREE_BASE="$PROJECT_DIR/.caws/worktrees"
+if [[ -d "$WORKTREE_BASE" ]]; then
+  if echo "$COMMAND" | grep -qE '\b(cp|mv)\b'; then
+    if echo "$COMMAND" | grep -qF ".caws/worktrees/" || echo "$COMMAND" | grep -qF "$WORKTREE_BASE"; then
+      # Check if the command references both a worktree path and the main repo
+      HAS_WT_PATH=false
+      HAS_MAIN_PATH=false
+      if echo "$COMMAND" | grep -qE '\.caws/worktrees/|'"$(echo "$WORKTREE_BASE" | sed 's/[\/&]/\\&/g')"''; then
+        HAS_WT_PATH=true
+      fi
+      # Check if destination/source is outside the worktree
+      if echo "$COMMAND" | grep -qE "(^|\s)$PROJECT_DIR/[^.]|core/|src/|tests/|packages/" && [[ "$HAS_WT_PATH" == "true" ]]; then
+        HAS_MAIN_PATH=true
+      fi
+      if [[ "$HAS_WT_PATH" == "true" ]] && [[ "$HAS_MAIN_PATH" == "true" ]]; then
+        echo "BLOCKED: Copying files between a worktree and the main repo is forbidden." >&2
+        echo "This bypasses worktree isolation. Work entirely within your worktree." >&2
+        echo "If tests need the main repo's venv, activate it with:" >&2
+        echo "  source $PROJECT_DIR/.venv/bin/activate" >&2
+        exit 2
+      fi
+    fi
+  fi
+fi
+
+# Only check git commands from here on
+if ! echo "$COMMAND" | grep -qE '(^|\s|&&|\|)git\s'; then
+  exit 0
+fi
+
+# --- Determine if worktrees are active ---
+WORKTREES_ACTIVE=false
+PARALLEL_BASE=""
+
+# Check .caws/parallel.json
+if [[ -f "$PROJECT_DIR/.caws/parallel.json" ]] && command -v node >/dev/null 2>&1; then
+  PARALLEL_INFO=$(node -e "
+    try {
+      var reg = JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.caws/parallel.json', 'utf8'));
+      var agents = (reg.agents || []).length;
+      console.log(agents + ':' + (reg.baseBranch || ''));
+    } catch(e) { console.log('0:'); }
+  " 2>/dev/null || echo "0:")
+
+  AGENT_COUNT=$(echo "$PARALLEL_INFO" | cut -d: -f1)
+  PARALLEL_BASE=$(echo "$PARALLEL_INFO" | cut -d: -f2)
+
+  if [[ "$AGENT_COUNT" -gt 0 ]] 2>/dev/null; then
+    WORKTREES_ACTIVE=true
+  fi
+fi
+
+# Check .caws/worktrees.json
+if [[ "$WORKTREES_ACTIVE" != "true" ]] && [[ -f "$PROJECT_DIR/.caws/worktrees.json" ]] && command -v node >/dev/null 2>&1; then
+  ACTIVE_COUNT=$(node -e "
+    try {
+      var reg = JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.caws/worktrees.json', 'utf8'));
+      var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active'; });
+      console.log(active.length);
+    } catch(e) { console.log('0'); }
+  " 2>/dev/null || echo "0")
+
+  if [[ "$ACTIVE_COUNT" -gt 0 ]] 2>/dev/null; then
+    WORKTREES_ACTIVE=true
+  fi
+fi
+
+# If no worktrees are active, allow everything
+if [[ "$WORKTREES_ACTIVE" != "true" ]]; then
+  exit 0
+fi
+
+# --- Block dangerous git operations when worktrees are active ---
+
+# Block git commit --amend
+if echo "$COMMAND" | grep -qE 'git\s+commit\s+.*--amend'; then
+  echo "BLOCKED: git commit --amend is not allowed while worktrees are active." >&2
+  echo "Amending commits risks rewriting another agent's work." >&2
+  echo "Create a new commit instead." >&2
+  exit 2
+fi
+
+# Block git stash (shared across worktrees)
+if echo "$COMMAND" | grep -qE 'git\s+stash' && ! echo "$COMMAND" | grep -qE 'git\s+stash\s+list'; then
+  echo "BLOCKED: git stash is not allowed while worktrees are active." >&2
+  echo "Stash is shared across all worktrees and can capture or destroy another agent's work." >&2
+  echo "Commit your changes to your branch instead." >&2
+  exit 2
+fi
+
+# Block git reset --hard
+if echo "$COMMAND" | grep -qE 'git\s+reset\s+--hard'; then
+  echo "BLOCKED: git reset --hard is not allowed while worktrees are active." >&2
+  echo "This could discard work that other agents depend on." >&2
+  exit 2
+fi
+
+# Block git push --force
+if echo "$COMMAND" | grep -qE 'git\s+push\s+.*(--force|-f\s)'; then
+  echo "BLOCKED: Force push is not allowed while worktrees are active." >&2
+  echo "This could rewrite history that other agents have based work on." >&2
+  exit 2
+fi
+
+# --- Base branch protections ---
+# Use the agent's actual working directory (CLAUDE_PROJECT_DIR), not the resolved
+# main repo root (PROJECT_DIR). In a worktree, PROJECT_DIR points to the main repo
+# (to find .caws/worktrees.json), but the agent's branch is in CLAUDE_PROJECT_DIR.
+AGENT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+CURRENT_BRANCH=$(cd "$AGENT_DIR" && git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+
+# Determine the base branch to protect
+BASE_BRANCH="$PARALLEL_BASE"
+if [[ -z "$BASE_BRANCH" ]] && [[ -f "$PROJECT_DIR/.caws/worktrees.json" ]] && command -v node >/dev/null 2>&1; then
+  BASE_BRANCH=$(node -e "
+    try {
+      var reg = JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.caws/worktrees.json', 'utf8'));
+      var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active'; });
+      if (active.length > 0) console.log(active[0].baseBranch || '');
+      else console.log('');
+    } catch(e) { console.log(''); }
+  " 2>/dev/null || echo "")
+fi
+
+if [[ -n "$BASE_BRANCH" ]] && [[ "$CURRENT_BRANCH" == "$BASE_BRANCH" ]]; then
+  # Block push from base branch
+  if echo "$COMMAND" | grep -qE 'git\s+push'; then
+    echo "BLOCKED: Pushing from the base branch ($BASE_BRANCH) while worktrees are active." >&2
+    echo "You should be working in a worktree, not on the base branch." >&2
+    echo "Use: cd .caws/worktrees/<name>/" >&2
+    exit 2
+  fi
+
+  # Allow git merge into base branch (merging completed worktree branches back)
+  # The commit-msg hook enforces the merge(worktree): message format
+  if echo "$COMMAND" | grep -qE 'git\s+merge\b'; then
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "additionalContext": "Merging into base branch ('"$BASE_BRANCH"') while worktrees are active. The commit-msg hook will enforce the merge(worktree): message format. Make sure the worktree for this branch has been destroyed first."
+      }
+    }'
+    exit 0
+  fi
+
+  # Warn (but don't block) commits on base branch — the pre-commit + commit-msg hooks handle blocking
+  if echo "$COMMAND" | grep -qE 'git\s+commit\b' && ! echo "$COMMAND" | grep -qE '--amend'; then
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "additionalContext": "WARNING: You are committing to the base branch ('"$BASE_BRANCH"') while worktrees are active. Only merge commits with the format merge(worktree): <description> are allowed. The pre-commit hook will block direct commits."
+      }
+    }'
+    exit 0
+  fi
+fi
+
+# Allow the command
+exit 0

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

@@ -0,0 +1,84 @@
+#!/bin/bash
+# CAWS Worktree Write Guard for Claude Code
+# Blocks Write/Edit on the base branch while worktrees are active.
+# This prevents agents from modifying files on main and then trying to
+# create worktrees retroactively to commit them.
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read JSON input from Claude Code
+INPUT=$(cat)
+
+# Extract tool info
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+# Only check Write and Edit tools
+case "$TOOL_NAME" in
+  Write|Edit) ;;
+  *) exit 0 ;;
+esac
+
+# --- Resolve main repo root ---
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+
+if command -v git >/dev/null 2>&1; then
+  GIT_COMMON_DIR=$(cd "$PROJECT_DIR" && git rev-parse --git-common-dir 2>/dev/null || echo "")
+  if [[ -n "$GIT_COMMON_DIR" ]] && [[ "$GIT_COMMON_DIR" != ".git" ]]; then
+    CANDIDATE=$(cd "$PROJECT_DIR" && cd "$GIT_COMMON_DIR/.." 2>/dev/null && pwd || echo "")
+    if [[ -n "$CANDIDATE" ]] && [[ -d "$CANDIDATE/.caws" ]]; then
+      PROJECT_DIR="$CANDIDATE"
+    fi
+  fi
+fi
+
+# --- Check for active worktrees ---
+if [[ ! -f "$PROJECT_DIR/.caws/worktrees.json" ]]; then
+  exit 0
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Use the agent's actual working directory, not the resolved main repo root.
+# In a worktree, PROJECT_DIR points to the main repo (to find .caws/worktrees.json),
+# but the agent's branch is in CLAUDE_PROJECT_DIR.
+AGENT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+CURRENT_BRANCH=$(cd "$AGENT_DIR" && git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+
+WT_INFO=$(node -e "
+  try {
+    var reg = JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.caws/worktrees.json', 'utf8'));
+    var active = Object.values(reg.worktrees || {}).filter(function(w) {
+      return w.status === 'active' && w.baseBranch === '$CURRENT_BRANCH';
+    });
+    console.log(active.length + ':' + active.map(function(w) { return w.name; }).join(', '));
+  } catch(e) { console.log('0:'); }
+" 2>/dev/null || echo "0:")
+
+WT_COUNT=$(echo "$WT_INFO" | cut -d: -f1)
+WT_NAMES=$(echo "$WT_INFO" | cut -d: -f2)
+
+if [[ "$WT_COUNT" -le 0 ]] 2>/dev/null; then
+  exit 0
+fi
+
+# Allow edits to .claude/ configuration (hooks, settings, rules)
+if [[ -n "$FILE_PATH" ]]; then
+  case "$FILE_PATH" in
+    */.claude/*|*/.caws/*) exit 0 ;;
+  esac
+fi
+
+# Block: we're on the base branch with active worktrees
+echo "BLOCKED: Cannot write/edit files on '$CURRENT_BRANCH' while $WT_COUNT worktree(s) are active: $WT_NAMES" >&2
+echo "" >&2
+echo "You MUST work in a worktree, not on the base branch." >&2
+echo "  To use an existing worktree: cd $PROJECT_DIR/.caws/worktrees/<name>/" >&2
+echo "  To create a new worktree:    caws worktree create <name>" >&2
+echo "" >&2
+echo "Do NOT make changes on main and create a worktree retroactively." >&2
+echo "The worktree must exist BEFORE you start making changes." >&2
+exit 2

package/dist/templates/.claude/rules/git-safety.md

@@ -0,0 +1,26 @@
+---
+description: Git safety rules for all agents
+globs:
+---
+
+# Git Safety
+
+## Commit discipline
+
+- Commit after each logical unit of work (a module + its tests, a bugfix, a refactor pass)
+- Use conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, `test:`, `perf:`
+- Never accumulate uncommitted changes across multiple unrelated concerns
+- Never leave uncommitted changes at session end; commit as `wip(<scope>): <description>` if incomplete
+
+## Forbidden operations
+
+- `git push --force` or `git push -f` -- never rewrite remote history
+- `git reset --hard` -- use `git stash` or `git checkout -- <file>` for targeted reverts (but not during parallel work)
+- `git clean -f` -- may delete another agent's untracked files
+- `git checkout .` or `git restore .` -- bulk discard is dangerous
+
+## Branch hygiene
+
+- Work on feature branches, not directly on main/master
+- One concern per branch
+- Delete branches after merging

package/dist/templates/.claude/rules/worktree-isolation.md

@@ -0,0 +1,51 @@
+---
+description: Rules for safe multi-agent git worktree isolation
+globs:
+---
+
+# Multi-Agent Worktree Safety
+
+When multiple agents are working on this project, each agent MUST work in its own git worktree. Never have two agents committing to the same branch.
+
+## Before starting work
+
+1. Check if worktrees exist: look for `.caws/worktrees.json` or `.caws/parallel.json`
+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>`
+
+## Forbidden operations when worktrees are active
+
+- `git commit --amend` -- rewrites history that other agents depend on
+- `git stash` / `git stash pop` -- stash is shared across all worktrees; using it can destroy another agent's uncommitted work
+- `git reset --hard` -- discards work that other agents may depend on
+- `git push --force` -- rewrites remote history
+- Direct commits to the base branch -- only `merge(worktree):` and `wip(checkpoint):` formats are allowed
+- Copying files between your worktree and the main repo directory -- defeats isolation
+
+## Merging worktree branches back to base
+
+Merge commits ARE allowed on the base branch while other worktrees are active. This lets you incrementally merge completed work without waiting for all agents to finish.
+
+1. Destroy the worktree first: `caws worktree destroy <name>`
+2. Switch to the base branch: `git checkout main`
+3. Merge with: `git merge --no-ff <worktree-branch>`
+4. The commit-msg hook enforces the `merge(worktree): <description>` format for non-FF merges
+5. For manual merge commits: `git commit -m "merge(worktree): integrate scenarios work"`
+
+## Virtual environment in worktrees
+
+Do NOT create a new virtual environment in your worktree. Use the main repo's venv:
+
+```bash
+source <main-repo-path>/.venv/bin/activate
+```
+
+If your project uses `.caws/scope.json`, the `designatedVenvPath` field specifies the correct venv location.
+
+## When your work is done
+
+1. Commit all changes to your worktree branch
+2. Run tests in your worktree to verify
+3. Destroy your worktree with `caws worktree destroy <name>`
+4. Merge your branch to base: `git merge --no-ff <branch>` (uses `merge(worktree):` format)
+5. Delete the branch if no longer needed: `git branch -d <branch>`

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

@@ -8,6 +8,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/worktree-guard.sh",
+            "timeout": 10
           }
         ]
       },
@@ -24,6 +29,11 @@
       {
         "matcher": "Write|Edit",
         "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/worktree-write-guard.sh",
+            "timeout": 10
+          },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/scope-guard.sh",
@@ -87,6 +97,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/audit.sh stop",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-worktree-check.sh",
+            "timeout": 10
           }
         ]
       }

package/dist/validation/spec-validation.js

@@ -112,6 +112,22 @@ const validateWorkingSpec = (spec, _options = {}) => {
       };
     }
 
+    // Validate status field if present
+    if (spec.status) {
+      const { SPEC_STATUSES } = require('../constants/spec-types');
+      if (!SPEC_STATUSES[spec.status]) {
+        return {
+          valid: false,
+          errors: [
+            {
+              instancePath: '/status',
+              message: `Invalid status '${spec.status}'. Valid values: ${Object.keys(SPEC_STATUSES).join(', ')}`,
+            },
+          ],
+        };
+      }
+    }
+
     // Validate experimental mode
     if (spec.experimental_mode) {
       if (typeof spec.experimental_mode !== 'object') {

package/dist/worktree/worktree-manager.js

@@ -206,6 +206,7 @@ function createWorktree(name, options = {}) {
     baseBranch: base,
     scope: scope || null,
     specId: specId || null,
+    owner: options.owner || process.env.CLAUDE_SESSION_ID || null,
     createdAt: new Date().toISOString(),
     status: 'active',
   };
@@ -276,27 +277,32 @@ function destroyWorktree(name, options = {}) {
     throw new Error(`Worktree '${name}' not found in registry`);
   }
 
-  // Remove git worktree
-  try {
-    const args = ['worktree', 'remove'];
-    if (force) args.push('--force');
-    args.push(entry.path);
-    execFileSync('git', args, { cwd: root, stdio: 'pipe' });
-  } catch (error) {
-    if (force) {
-      // Force cleanup: remove directory manually
-      if (fs.existsSync(entry.path)) {
+  // Remove git worktree — handle already-deleted directories gracefully
+  const dirExists = fs.existsSync(entry.path);
+  if (dirExists) {
+    try {
+      const args = ['worktree', 'remove'];
+      if (force) args.push('--force');
+      args.push(entry.path);
+      execFileSync('git', args, { cwd: root, stdio: 'pipe' });
+    } catch (error) {
+      if (force) {
+        // Force cleanup: remove directory manually
         fs.removeSync(entry.path);
+      } else {
+        throw new Error(`Failed to remove worktree: ${error.message}. Use --force to override.`);
       }
-      // Prune git worktree list
-      try {
-        execFileSync('git', ['worktree', 'prune'], { cwd: root, stdio: 'pipe' });
-      } catch {
-        // Non-fatal
-      }
-    } else {
-      throw new Error(`Failed to remove worktree: ${error.message}. Use --force to override.`);
     }
+  } else {
+    // Directory already gone — just clean up git's tracking
+    console.log(`   Worktree directory already removed, cleaning up registry`);
+  }
+
+  // Always prune git's worktree list to stay in sync
+  try {
+    execFileSync('git', ['worktree', 'prune'], { cwd: root, stdio: 'pipe' });
+  } catch {
+    // Non-fatal
   }
 
   // Optionally delete branch
@@ -337,15 +343,19 @@ function pruneWorktrees(options = {}) {
   for (const [name, entry] of Object.entries(registry.worktrees)) {
     const created = new Date(entry.createdAt);
     const ageDays = (now - created) / (1000 * 60 * 60 * 24);
+    const dirExists = fs.existsSync(entry.path);
 
     const shouldPrune =
+      // Always prune destroyed entries
       entry.status === 'destroyed' ||
-      (!fs.existsSync(entry.path) && ageDays > maxAgeDays) ||
-      (maxAgeDays === 0 && entry.status === 'destroyed');
+      // Prune active entries whose directory is gone (filesystem-registry desync)
+      (entry.status === 'active' && !dirExists) ||
+      // Prune old missing entries
+      (!dirExists && ageDays > maxAgeDays);
 
     if (shouldPrune) {
       // Clean up filesystem if still exists
-      if (fs.existsSync(entry.path)) {
+      if (dirExists) {
         try {
           execFileSync('git', ['worktree', 'remove', '--force', entry.path], {
             cwd: root,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "8.3.0",
+  "version": "9.0.0",
   "description": "CAWS CLI - Coding Agent Workflow System command-line tools for spec management, quality gates, and AI-assisted development",
   "main": "dist/index.js",
   "bin": {

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

@@ -1,6 +1,7 @@
 #!/bin/bash
 # CAWS Scope Guard Hook for Claude Code
-# Validates file edits against the working spec's scope boundaries
+# Validates file edits against scope boundaries from working-spec + feature specs
+# Specs with terminal status (completed, closed, archived) are skipped
 # @author @darianrosebrook
 
 set -euo pipefail
@@ -25,8 +26,8 @@ PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 SPEC_FILE="$PROJECT_DIR/.caws/working-spec.yaml"
 SCOPE_FILE="$PROJECT_DIR/.caws/scope.json"
 
-# Check if spec file or scope.json exists
-if [[ ! -f "$SPEC_FILE" ]] && [[ ! -f "$SCOPE_FILE" ]]; then
+# Check if any spec infrastructure exists
+if [[ ! -f "$SPEC_FILE" ]] && [[ ! -f "$SCOPE_FILE" ]] && [[ ! -d "$PROJECT_DIR/.caws/specs" ]]; then
   exit 0
 fi
 
@@ -119,7 +120,9 @@ if [[ ! -f "$SPEC_FILE" ]] && [[ -f "$SCOPE_FILE" ]]; then
   fi
 fi
 
-# Use Node.js to parse YAML and check scope
+# Use Node.js to parse YAML and check scope across working spec + active feature specs
+SPECS_DIR="$PROJECT_DIR/.caws/specs"
+
 if command -v node >/dev/null 2>&1; then
   SCOPE_CHECK=$(node -e "
     const yaml = require('js-yaml');
@@ -127,26 +130,67 @@ if command -v node >/dev/null 2>&1; then
     const path = require('path');
 
     try {
-      const spec = yaml.load(fs.readFileSync('$SPEC_FILE', 'utf8'));
       const filePath = '$REL_PATH';
 
-      // Check if file is explicitly out of scope
-      const outOfScope = spec.scope?.out || [];
-      for (const pattern of outOfScope) {
-        // Simple glob-like matching
-        const regex = new RegExp(pattern.replace(/\*/g, '.*').replace(/\?/g, '.'));
-        if (regex.test(filePath)) {
-          console.log('out_of_scope:' + pattern);
-          process.exit(0);
+      // Terminal statuses: specs that are done — scope no longer enforced
+      const TERMINAL = new Set(['completed', 'closed', 'archived']);
+
+      // Smart allowlist: root-level files, .caws/, .claude/ always pass
+      if (!filePath.includes('/') || filePath.startsWith('.caws/') || filePath.startsWith('.claude/')) {
+        console.log('in_scope');
+        process.exit(0);
+      }
+
+      // Collect all active specs (working-spec + feature specs)
+      const specs = [];
+
+      // 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 (_) {}
+      }
+
+      // 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'))) {
+          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 (_) {}
         }
       }
 
-      // Check if file is in scope (if scope is explicitly defined)
-      const inScope = spec.scope?.in || [];
-      if (inScope.length > 0) {
+      // No active specs — allow everything
+      if (specs.length === 0) {
+        console.log('in_scope');
+        process.exit(0);
+      }
+
+      // Check scope.out across ALL active specs — any match blocks
+      for (const { source, spec } of specs) {
+        for (const pattern of (spec.scope?.out || [])) {
+          const regex = new RegExp(pattern.replace(/\\*/g, '.*').replace(/\\?/g, '.'));
+          if (regex.test(filePath)) {
+            console.log('out_of_scope:' + source + ':' + pattern);
+            process.exit(0);
+          }
+        }
+      }
+
+      // Union all scope.in patterns — file must match at least one
+      const allInScope = specs.flatMap(({ spec }) => spec.scope?.in || []);
+      if (allInScope.length > 0) {
         let found = false;
-        for (const pattern of inScope) {
-          const regex = new RegExp(pattern.replace(/\*/g, '.*').replace(/\?/g, '.'));
+        for (const pattern of allInScope) {
+          const regex = new RegExp(pattern.replace(/\\*/g, '.*').replace(/\\?/g, '.'));
           if (regex.test(filePath)) {
             found = true;
             break;
@@ -165,12 +209,14 @@ if command -v node >/dev/null 2>&1; then
   " 2>&1)
 
   if [[ "$SCOPE_CHECK" == out_of_scope:* ]]; then
-    PATTERN="${SCOPE_CHECK#out_of_scope:}"
+    DETAIL="${SCOPE_CHECK#out_of_scope:}"
+    SOURCE="${DETAIL%%:*}"
+    PATTERN="${DETAIL#*:}"
     echo '{
       "hookSpecificOutput": {
         "hookEventName": "PreToolUse",
         "permissionDecision": "ask",
-        "permissionDecisionReason": "This file ('"$REL_PATH"') is marked as out-of-scope in the working spec (pattern: '"$PATTERN"'). Editing it may cause scope creep. Please confirm this edit is intentional."
+        "permissionDecisionReason": "This file ('"$REL_PATH"') is marked as out-of-scope in '"$SOURCE"' (pattern: '"$PATTERN"'). Editing it may cause scope creep. Please confirm this edit is intentional."
       }
     }'
     exit 0
@@ -181,7 +227,7 @@ if command -v node >/dev/null 2>&1; then
       "hookSpecificOutput": {
         "hookEventName": "PreToolUse",
         "permissionDecision": "ask",
-        "permissionDecisionReason": "This file ('"$REL_PATH"') is not in the defined scope of the working spec. Editing it may cause scope creep. Please confirm this edit is intentional."
+        "permissionDecisionReason": "This file ('"$REL_PATH"') is not in the defined scope of any active spec. Editing it may cause scope creep. Please confirm this edit is intentional."
       }
     }'
     exit 0