@paths.design/caws-cli 8.3.0 → 9.1.0

package/dist/scaffold/git-hooks.js

@@ -236,6 +236,128 @@ if [ "$YAML_VALIDATION_FAILED" = true ]; then
   exit 1
 fi
 
+# ===== CAWS Multi-Agent Safety Guard =====
+# Prevents unsafe concurrent operations on shared branches
+
+if [ -d ".caws" ]; then
+  CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+
+  # Guard 1a: Block commits on base branch when parallel worktrees are active (caws parallel)
+  if [ -f ".caws/parallel.json" ] && command -v node >/dev/null 2>&1; then
+    PARALLEL_BASE=$(node -e "
+      try {
+        var reg = JSON.parse(require('fs').readFileSync('.caws/parallel.json', 'utf8'));
+        console.log(reg.baseBranch || '');
+      } catch(e) { console.log(''); }
+    " 2>/dev/null)
+
+    if [ -n "$PARALLEL_BASE" ] && [ "$CURRENT_BRANCH" = "$PARALLEL_BASE" ]; then
+      AGENT_COUNT=$(node -e "
+        try {
+          var reg = JSON.parse(require('fs').readFileSync('.caws/parallel.json', 'utf8'));
+          console.log((reg.agents || []).length);
+        } catch(e) { console.log('0'); }
+      " 2>/dev/null)
+
+      if [ "$AGENT_COUNT" -gt 0 ] 2>/dev/null; then
+        echo "BLOCKED: Committing to '$CURRENT_BRANCH' while $AGENT_COUNT parallel agent worktree(s) are active."
+        echo "  Active agents are working in isolated worktrees."
+        echo "  Committing to the base branch risks interleaved history and merge conflicts."
+        echo ""
+        echo "  To see parallel status: caws parallel status"
+        echo "  To merge agent work:    caws parallel merge"
+        echo "  To override (unsafe):   git commit --no-verify"
+        exit 1
+      fi
+    fi
+  fi
+
+  # Guard 1b: Block commits on base branch when ANY active worktrees exist (caws worktree create)
+  if [ -f ".caws/worktrees.json" ] && command -v node >/dev/null 2>&1; then
+    ACTIVE_WORKTREES=$(node -e "
+      try {
+        var reg = JSON.parse(require('fs').readFileSync('.caws/worktrees.json', 'utf8'));
+        var wts = Object.values(reg.worktrees || {});
+        var active = wts.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)
+
+    WT_COUNT=$(echo "$ACTIVE_WORKTREES" | cut -d: -f1)
+    WT_NAMES=$(echo "$ACTIVE_WORKTREES" | cut -d: -f2)
+
+    if [ "$WT_COUNT" -gt 0 ] 2>/dev/null; then
+      echo "BLOCKED: Committing to '$CURRENT_BRANCH' while $WT_COUNT active worktree(s) exist: $WT_NAMES"
+      echo "  You should be working in your worktree, not on the base branch."
+      echo "  Committing here risks interleaved history with agents in worktrees."
+      echo ""
+      echo "  To work in your worktree: cd .caws/worktrees/<name>/"
+      echo "  To see worktrees:         caws worktree list"
+      echo "  To override (unsafe):     git commit --no-verify"
+      exit 1
+    fi
+  fi
+
+  # Guard 2: Warn if multiple active sessions exist on same branch
+  if [ -f ".caws/sessions.json" ] && command -v node >/dev/null 2>&1; then
+    ACTIVE_ON_BRANCH=$(node -e "
+      try {
+        var reg = JSON.parse(require('fs').readFileSync('.caws/sessions.json', 'utf8'));
+        var count = Object.values(reg.sessions || {}).filter(
+          function(s) { return s.status === 'active' && s.branch === '$CURRENT_BRANCH'; }
+        ).length;
+        console.log(count);
+      } catch(e) { console.log('0'); }
+    " 2>/dev/null)
+
+    if [ "$ACTIVE_ON_BRANCH" -gt 1 ] 2>/dev/null; then
+      echo "WARNING: $ACTIVE_ON_BRANCH active sessions detected on branch '$CURRENT_BRANCH'."
+      echo "  Multiple agents committing to the same branch risks interleaved history."
+      echo "  Consider using worktrees: caws parallel setup <plan-file>"
+      echo ""
+    fi
+  fi
+
+  # Guard 3: Block --amend when HEAD commit may not belong to current session
+  # Detect --amend by inspecting the parent git process arguments
+  AMEND_FLAG=false
+  if command -v ps >/dev/null 2>&1; then
+    PARENT_ARGS=$(ps -o args= -p $PPID 2>/dev/null || echo "")
+    case "$PARENT_ARGS" in
+      *--amend*) AMEND_FLAG=true ;;
+    esac
+  fi
+
+  if [ "$AMEND_FLAG" = true ]; then
+    BLOCK_AMEND=false
+    if [ -f ".caws/parallel.json" ]; then
+      BLOCK_AMEND=true
+    elif [ -f ".caws/worktrees.json" ] && command -v node >/dev/null 2>&1; then
+      HAS_ACTIVE_WT=$(node -e "
+        try {
+          var reg = JSON.parse(require('fs').readFileSync('.caws/worktrees.json', 'utf8'));
+          var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active'; });
+          console.log(active.length > 0 ? 'yes' : 'no');
+        } catch(e) { console.log('no'); }
+      " 2>/dev/null)
+      if [ "$HAS_ACTIVE_WT" = "yes" ]; then
+        BLOCK_AMEND=true
+      fi
+    fi
+
+    if [ "$BLOCK_AMEND" = true ]; then
+      echo "BLOCKED: --amend is not allowed while worktrees are active."
+      echo "  Amending commits risks rewriting another agent's work."
+      echo "  Create a new commit instead."
+      echo "  To override (dangerous): git commit --amend --no-verify"
+      exit 1
+    fi
+  fi
+fi
+# ===== End Multi-Agent Safety Guard =====
+
 # Fallback chain for quality gates:
 # 1. Try Node.js script (if exists)
 # 2. Try CAWS CLI
@@ -477,73 +599,63 @@ if [ ! -d ".caws" ]; then
   exit 0
 fi
 
-# Run full validation suite
+# Run CAWS validation (supports multi-spec projects)
+CAWS_VALIDATION_FAILED=false
 if command -v caws >/dev/null 2>&1; then
-  echo "Running comprehensive CAWS validation..."
-  
-  # Run validation and capture output
-  VALIDATION_OUTPUT=$(caws validate 2>&1)
-  VALIDATION_EXIT=$?
-  
-  if [ $VALIDATION_EXIT -eq 0 ]; then
-    echo "CAWS validation passed"
-  else
-    echo "CAWS validation failed"
-    echo ""
-    echo "==================================================="
-    echo "Validation Errors:"
-    echo "==================================================="
-    echo "$VALIDATION_OUTPUT" | grep -E "(|error|Error|Missing|required)" || echo "$VALIDATION_OUTPUT"
-    echo ""
-    
-    # Check for contract-related errors
-    if echo "$VALIDATION_OUTPUT" | grep -qi "contract"; then
-      echo "Contract Requirements:"
-      echo "   - Tier 1 & 2 changes require at least one contract"
-      echo "   - For infrastructure/setup work, use 'chore' mode or add a minimal contract:"
-      echo ""
-      echo "   Example minimal contract (.caws/working-spec.yaml):"
-      echo "   contracts:"
-      echo "     - type: 'project_setup'"
-      echo "       path: '.caws/working-spec.yaml'"
-      echo "       description: 'Project-level CAWS configuration'"
-      echo ""
-      echo "   Or change mode to 'chore' for maintenance work:"
-      echo "   mode: chore"
-      echo ""
+  echo "Running CAWS validation..."
+
+  # Multi-spec project: validate each open spec individually
+  if [ -d ".caws/specs" ] && command -v node >/dev/null 2>&1; then
+    OPEN_SPECS=$(node -e "
+      var fs = require('fs'), path = require('path'), dir = '.caws/specs';
+      try {
+        fs.readdirSync(dir).filter(function(f) { return f.endsWith('.yaml'); }).forEach(function(f) {
+          var content = fs.readFileSync(path.join(dir, f), 'utf8');
+          if (content.indexOf('status: closed') === -1) {
+            var match = content.match(/^id:\\s*(.+)$/m);
+            if (match) console.log(match[1].trim());
+          }
+        });
+      } catch(e) {}
+    " 2>/dev/null || echo "")
+
+    if [ -n "$OPEN_SPECS" ]; then
+      echo "  Multi-spec project detected, validating open specs..."
+      while IFS= read -r spec_id; do
+        [ -z "$spec_id" ] && continue
+        echo "  Validating spec: $spec_id"
+        if ! caws validate --spec-id "$spec_id" --quiet 2>&1; then
+          echo "  Validation failed for spec: $spec_id"
+          CAWS_VALIDATION_FAILED=true
+        fi
+      done <<< "$OPEN_SPECS"
+      if [ "$CAWS_VALIDATION_FAILED" = false ]; then
+        echo "CAWS validation passed (all open specs)"
+      fi
+    else
+      echo "  No open specs found, skipping CAWS validation"
     fi
-    
-    # Check for active waivers
-    echo "Checking for active waivers..."
-    if command -v caws >/dev/null 2>&1 && caws waivers list --status=active --format=count 2>/dev/null | grep -q "[1-9]"; then
-      ACTIVE_WAIVERS=$(caws waivers list --status=active 2>/dev/null)
-      echo "Active waivers found:"
-      echo "$ACTIVE_WAIVERS" | head -5
-      echo ""
-      echo "Note: Waivers may not cover all validation failures"
-      echo "   Review waiver coverage: caws waivers list --status=active"
+  else
+    # Single-spec project: validate working-spec directly
+    VALIDATION_OUTPUT=$(caws validate --quiet 2>&1)
+    if [ $? -ne 0 ]; then
+      echo "$VALIDATION_OUTPUT"
+      CAWS_VALIDATION_FAILED=true
     else
-      echo "   No active waivers found"
-      echo ""
-      echo "If this is infrastructure/setup work, you can create a waiver:"
-      echo "   caws waivers create \\\\"
-      echo "     --title='Initial CAWS setup' \\\\"
-      echo "     --reason=infrastructure_limitation \\\\"
-      echo "     --gates=contracts \\\\"
-      echo "     --expires-at='2024-12-31T23:59:59Z' \\\\"
-      echo "     --approved-by='@your-team' \\\\"
-      echo "     --impact-level=low \\\\"
-      echo "     --mitigation-plan='Contracts will be added as features are developed'"
+      echo "CAWS validation passed"
     fi
-    
+  fi
+
+  if [ "$CAWS_VALIDATION_FAILED" = true ]; then
     echo ""
     echo "==================================================="
+    echo "CAWS validation failed"
+    echo "==================================================="
     echo "Next Steps:"
     echo "   1. Review errors above"
-    echo "   2. Fix issues in .caws/working-spec.yaml"
-    echo "   3. Run: caws validate \\(to verify fixes\\)"
-    echo "   4. Commit fixes: git commit --no-verify \\(allowed\\)"
-    echo "   5. Push again: git push"
+    echo "   2. Fix issues in .caws/working-spec.yaml or .caws/specs/"
+    echo "   3. Run: caws validate (to verify fixes)"
+    echo "   4. Push again: git push"
     echo "==================================================="
     exit 1
   fi
@@ -665,37 +777,89 @@ echo "All quality gates passed - ready to push"
 function generateCommitMsgHook() {
   return `#!/bin/bash
 # CAWS Commit Message Hook
-# Validates commit message format
+# Validates commit message format and enforces merge(worktree): convention
 
 COMMIT_MSG_FILE=$1
 
 # Read the commit message
 COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
 
+# Resolve CAWS root (works from worktrees too)
+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
+
 # Check if CAWS is initialized
-if [ ! -d ".caws" ]; then
+if [ ! -d "$CAWS_ROOT/.caws" ]; then
   exit 0
 fi
 
+# ===== Worktree merge message guard =====
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null || echo ".git")
+HAS_ACTIVE_WORKTREES=false
+
+if [ -f "$CAWS_ROOT/.caws/worktrees.json" ] && command -v node >/dev/null 2>&1; then
+  WT_COUNT=$(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' && w.baseBranch === '$CURRENT_BRANCH';
+      });
+      console.log(active.length);
+    } catch(e) { console.log('0'); }
+  " 2>/dev/null)
+  if [ "$WT_COUNT" -gt 0 ] 2>/dev/null; then
+    HAS_ACTIVE_WORKTREES=true
+  fi
+fi
+
+if [ "$HAS_ACTIVE_WORKTREES" = true ]; then
+  IS_GIT_MERGE=false
+  if [ -f "$GIT_DIR/MERGE_HEAD" ]; then
+    IS_GIT_MERGE=true
+  fi
+
+  if [[ "$COMMIT_MSG" =~ ^merge\\(worktree\\): ]] || [ "$IS_GIT_MERGE" = true ]; then
+    echo "Merge commit to base branch allowed (worktrees active)"
+  elif [[ "$COMMIT_MSG" =~ ^wip\\(checkpoint\\): ]]; then
+    echo "Checkpoint commit allowed (prior-session cleanup)"
+  else
+    echo "BLOCKED: Direct commit to '$CURRENT_BRANCH' while worktrees are active."
+    echo "  Only these commit types are allowed on the base branch during parallel work:"
+    echo ""
+    echo "  merge(worktree): <description>     — merge a completed worktree branch"
+    echo "  wip(checkpoint): <description>     — commit prior-session dirty files"
+    echo "  git merge --no-ff <branch>         — git merge commit"
+    echo ""
+    echo "  To override (unsafe):   git commit --no-verify"
+    exit 1
+  fi
+fi
+# ===== End worktree merge message guard =====
+
 # Basic commit message validation
 if [ \${#COMMIT_MSG} -lt 10 ]; then
-  echo "Commit message too short \\(minimum 10 characters\\)"
-  echo "Write descriptive commit messages"
+  echo "Commit message too short (minimum 10 characters)"
+  echo "  Write descriptive commit messages"
   exit 1
 fi
 
 # Check for conventional commit format (optional but encouraged)
-if [[ $COMMIT_MSG =~ ^(feat|fix|docs|style|refactor|test|chore)(.+)? ]]; then
-  echo "Conventional commit format detected"
+if [[ $COMMIT_MSG =~ ^(feat|fix|docs|style|refactor|test|chore|merge|perf|wip)(\\(.*\\))?: ]]; then
+  : # valid format
 else
-  echo "Consider using conventional commit format:"
-  echo "   feat: add new feature"
-  echo "   fix: bug fix"
-  echo "   docs: documentation"
-  echo "   style: formatting"
-  echo "   refactor: code restructuring"
-  echo "   test: testing"
-  echo "   chore: maintenance"
+  if [[ ! $COMMIT_MSG =~ ^Merge\\ (branch|remote) ]]; then
+    echo "Consider using conventional commit format:"
+    echo "   feat: / fix: / docs: / refactor: / chore: / merge(worktree):"
+  fi
 fi
 
 echo "Commit message validation passed"

package/dist/scaffold/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scaffold/index.js"],"names":[],"mappings":"AA8MA;;;GAGG;AACH,6DA6jBC;AAztBD;;;GAyIC;;AAMD;;;GAGG;AACH,yDAGC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scaffold/index.js"],"names":[],"mappings":"AA4MA;;;GAGG;AACH,6DAikBC;AAxtBD;;;GAoIC;;AAMD;;;GAGG;AACH,yDAGC"}

package/dist/session/session-manager.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Start a new session, creating the initial capsule with baseline state
+ * @param {Object} options - Session options
+ * @param {string} [options.role] - Agent role (worker, integrator, qa)
+ * @param {string} [options.specId] - Associated feature spec ID
+ * @param {string[]} [options.allowedGlobs] - Allowed file patterns
+ * @param {string[]} [options.forbiddenGlobs] - Forbidden file patterns
+ * @param {string} [options.intent] - What this session intends to accomplish
+ * @returns {Object} Created capsule
+ */
+export function startSession(options?: {
+    role?: string;
+    specId?: string;
+    allowedGlobs?: string[];
+    forbiddenGlobs?: string[];
+    intent?: string;
+}): any;
+/**
+ * Add a checkpoint to the current (most recent active) session
+ * @param {Object} data - Checkpoint data
+ * @param {string} [data.sessionId] - Specific session ID (uses latest active if omitted)
+ * @param {string[]} [data.pathsTouched] - Files changed
+ * @param {string[]} [data.artifactsWritten] - Generated artifacts
+ * @param {Object[]} [data.testsRun] - Test results { name, status, evidence }
+ * @param {Object[]} [data.determinismChecks] - Determinism checks { name, status, total }
+ * @param {Object[]} [data.knownIssues] - Issues discovered { type, description }
+ * @param {string} [data.intent] - Updated intent description
+ * @returns {Object} Updated capsule
+ */
+export function checkpointSession(data?: {
+    sessionId?: string;
+    pathsTouched?: string[];
+    artifactsWritten?: string[];
+    testsRun?: any[];
+    determinismChecks?: any[];
+    knownIssues?: any[];
+    intent?: string;
+}): any;
+/**
+ * End a session, finalizing the capsule with handoff information
+ * @param {Object} data - End session data
+ * @param {string} [data.sessionId] - Specific session ID (uses latest active if omitted)
+ * @param {string[]} [data.nextActions] - What the next session should do
+ * @param {string[]} [data.riskNotes] - Risk notes for handoff
+ * @returns {Object} Finalized capsule
+ */
+export function endSession(data?: {
+    sessionId?: string;
+    nextActions?: string[];
+    riskNotes?: string[];
+}): any;
+/**
+ * List all sessions
+ * @param {Object} [options] - List options
+ * @param {string} [options.status] - Filter by status (active, completed)
+ * @param {number} [options.limit] - Max entries to return
+ * @returns {Object[]} Session entries
+ */
+export function listSessions(options?: {
+    status?: string;
+    limit?: number;
+}): any[];
+/**
+ * Show a specific session's full capsule
+ * @param {string} sessionId - Session ID (or "latest" for most recent)
+ * @returns {Object} Full capsule
+ */
+export function showSession(sessionId: string): any;
+/**
+ * Briefing output for session start hooks - returns structured text
+ * @returns {string} Briefing text
+ */
+export function getBriefing(): string;
+/**
+ * Load the session registry
+ * @param {string} root - Repository root
+ * @returns {Object} Registry object
+ */
+export function loadRegistry(root: string): any;
+/**
+ * Get the git repository root
+ * @returns {string} Absolute path to repo root
+ */
+export function getRepoRoot(): string;
+export const SESSIONS_DIR: ".caws/sessions";
+export const REGISTRY_FILE: ".caws/sessions.json";
+export const CAPSULE_SCHEMA_VERSION: "caws.capsule.v1";
+/**
+ * Find all active sessions on a specific branch
+ * @param {string} branch - Branch name to search
+ * @returns {Object[]} Active sessions on that branch with id and metadata
+ */
+export function findActiveSessionsOnBranch(branch: string): any[];
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/session/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../src/session/session-manager.js"],"names":[],"mappings":"AA4JA;;;;;;;;;GASG;AACH,uCAPG;IAAyB,IAAI,GAArB,MAAM;IACW,MAAM,GAAvB,MAAM;IACa,YAAY,GAA/B,MAAM,EAAE;IACW,cAAc,GAAjC,MAAM,EAAE;IACS,MAAM,GAAvB,MAAM;CACd,OAyFF;AAED;;;;;;;;;;;GAWG;AACH,yCATG;IAAsB,SAAS,GAAvB,MAAM;IACU,YAAY,GAA5B,MAAM,EAAE;IACQ,gBAAgB,GAAhC,MAAM,EAAE;IACQ,QAAQ,GAAxB,KAAQ;IACQ,iBAAiB,GAAjC,KAAQ;IACQ,WAAW,GAA3B,KAAQ;IACM,MAAM,GAApB,MAAM;CACd,OAwDF;AAED;;;;;;;GAOG;AACH,kCALG;IAAsB,SAAS,GAAvB,MAAM;IACU,WAAW,GAA3B,MAAM,EAAE;IACQ,SAAS,GAAzB,MAAM,EAAE;CAChB,OAgEF;AAED;;;;;;GAMG;AACH,uCAJG;IAAyB,MAAM,GAAvB,MAAM;IACW,KAAK,GAAtB,MAAM;CACd,GAAU,KAAQ,CAuBpB;AAED;;;;GAIG;AACH,uCAHW,MAAM,OA2BhB;AAED;;;GAGG;AACH,+BAFa,MAAM,CA8DlB;AAlZD;;;;GAIG;AACH,mCAHW,MAAM,OAahB;AApHD;;;GAGG;AACH,+BAFa,MAAM,CAMlB;AAZD,2BAAqB,gBAAgB,CAAC;AACtC,4BAAsB,qBAAqB,CAAC;AAC5C,qCAA+B,iBAAiB,CAAC;AAwgBjD;;;;GAIG;AACH,mDAHW,MAAM,GACJ,KAAQ,CAQpB"}

package/dist/session/session-manager.js

@@ -533,6 +533,19 @@ function findActiveSession(registry) {
   return active.length > 0 ? active[0][0] : null;
 }
 
+/**
+ * Find all active sessions on a specific branch
+ * @param {string} branch - Branch name to search
+ * @returns {Object[]} Active sessions on that branch with id and metadata
+ */
+function findActiveSessionsOnBranch(branch) {
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+  return Object.entries(registry.sessions)
+    .filter(([, meta]) => meta.status === 'active' && meta.branch === branch)
+    .map(([id, meta]) => ({ id, ...meta }));
+}
+
 module.exports = {
   startSession,
   checkpointSession,
@@ -545,4 +558,5 @@ module.exports = {
   SESSIONS_DIR,
   REGISTRY_FILE,
   CAPSULE_SCHEMA_VERSION,
+  findActiveSessionsOnBranch,
 };

package/dist/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