@paths.design/caws-cli 8.3.0 → 9.1.0

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

package/templates/.claude/hooks/session-caws-status.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+# CAWS Session Status Hook for Claude Code
+# Reports project state at session start with worktree warnings
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read stdin (required by hook protocol)
+INPUT=$(cat)
+
+# Only run for session-start events
+EVENT_TYPE="${1:-}"
+if [ "$EVENT_TYPE" != "session-start" ]; then
+  exit 0
+fi
+
+# Check if this is a CAWS project
+if [ ! -d "${CLAUDE_PROJECT_DIR:-.}/.caws" ]; then
+  exit 0
+fi
+
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+# --- Resolve main repo root ---
+CAWS_ROOT="."
+if command -v git >/dev/null 2>&1; then
+  _GIT_COMMON=$(git rev-parse --git-common-dir 2>/dev/null || echo ".git")
+  if [ "$_GIT_COMMON" != ".git" ]; then
+    _CANDIDATE=$(cd "$_GIT_COMMON/.." 2>/dev/null && pwd || echo "")
+    if [ -n "$_CANDIDATE" ] && [ -d "$_CANDIDATE/.caws" ]; then
+      CAWS_ROOT="$_CANDIDATE"
+    fi
+  fi
+fi
+
+# --- Active worktree warning ---
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+
+if [ -f "$CAWS_ROOT/.caws/worktrees.json" ] && command -v node >/dev/null 2>&1; then
+  WT_INFO=$(node -e "
+    try {
+      var reg = JSON.parse(require('fs').readFileSync('$CAWS_ROOT/.caws/worktrees.json', 'utf8'));
+      var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active'; });
+      if (active.length > 0) {
+        var names = active.map(function(w) { return w.name + ' (' + w.branch + ')'; });
+        console.log(active.length + ':' + names.join(', '));
+      } else {
+        console.log('0:');
+      }
+    } 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" -gt 0 ] 2>/dev/null; then
+    # Check if the agent is already in a worktree (not on the base branch)
+    BASE_BRANCH=$(node -e "
+      try {
+        var reg = JSON.parse(require('fs').readFileSync('$CAWS_ROOT/.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 "")
+
+    echo ""
+    echo "================================================================"
+    echo "  ACTIVE WORKTREES DETECTED: $WT_COUNT worktree(s)"
+    echo "  $WT_NAMES"
+    echo "================================================================"
+
+    if [ -n "$BASE_BRANCH" ] && [ "$CURRENT_BRANCH" = "$BASE_BRANCH" ]; then
+      echo ""
+      echo "  You MUST work in a worktree, not on $CURRENT_BRANCH."
+      echo ""
+      echo "  If a worktree was created for your task:"
+      echo "    cd $CAWS_ROOT/.caws/worktrees/<name>/"
+      echo ""
+      echo "  If you need a new worktree:"
+      echo "    caws worktree create <name>"
+      echo ""
+      echo "  The only operations allowed on $CURRENT_BRANCH are:"
+      echo "    - git merge --no-ff <branch> (merge completed worktree work)"
+      echo "    - Commits with message: merge(worktree): <description>"
+      echo "    - Commits with message: wip(checkpoint): <description>"
+      echo "      (for committing prior-session dirty files)"
+      echo ""
+      echo "  Writing or editing files on $CURRENT_BRANCH will be BLOCKED"
+      echo "  by the PreToolUse hook while worktrees are active."
+    else
+      echo ""
+      echo "  You are on branch '$CURRENT_BRANCH' (worktree). Good."
+      echo "  Other active worktrees: $WT_NAMES"
+    fi
+    echo "================================================================"
+    echo ""
+  fi
+fi
+
+# Use caws session briefing for structured output
+if command -v caws &>/dev/null; then
+  caws session briefing 2>/dev/null || {
+    echo "--- CAWS Session Briefing (fallback) ---"
+    HEAD_SHA=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+    BRANCH=$(git branch --show-current 2>/dev/null || echo "detached")
+    DIRTY_COUNT=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+    echo "Git: ${BRANCH} @ ${HEAD_SHA} (${DIRTY_COUNT} dirty files)"
+    if [ "$DIRTY_COUNT" -gt 0 ]; then
+      echo "WARNING: Working tree has uncommitted changes from a prior session."
+      echo "Classify and commit or stash them before starting new work."
+    fi
+    echo "--- End CAWS Briefing ---"
+  }
+fi
+
+exit 0