@paths.design/caws-cli 9.1.1 → 9.3.0

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

@@ -65,13 +65,22 @@ if [[ "$WT_COUNT" -le 0 ]] 2>/dev/null; then
   exit 0
 fi
 
-# Allow edits to .claude/ configuration (hooks, settings, rules)
+# Allow edits to configuration and documentation (benign, no merge conflict risk)
 if [[ -n "$FILE_PATH" ]]; then
   case "$FILE_PATH" in
     */.claude/*|*/.caws/*) exit 0 ;;
+    */docs/*) exit 0 ;;
   esac
 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.
+MERGE_HEAD_PATH=$(cd "$AGENT_DIR" && git rev-parse --git-dir 2>/dev/null || echo ".git")
+if [[ -f "$MERGE_HEAD_PATH/MERGE_HEAD" ]]; then
+  exit 0
+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
@@ -81,4 +90,7 @@ 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
+echo "" >&2
+echo "If you are merging a worktree branch, use: caws worktree merge <name>" >&2
+echo "Or start the merge first (git merge --no-ff <branch>), then resolve conflicts." >&2
 exit 2

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

@@ -9,29 +9,62 @@ When multiple agents are working on this project, each agent MUST work in its ow
 
 ## Before starting work
 
-1. Check if worktrees exist: look for `.caws/worktrees.json` or `.caws/parallel.json`
+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.
 
 ## Forbidden operations when worktrees are active
 
 - `git commit --amend` -- rewrites history that other agents depend on
+- `git rebase` -- rewrites branch history; the hook blocks this automatically while worktrees are active. If you need code from main, create a new worktree from current main instead
+- `git cherry-pick` -- replays commits across branches; blocked while worktrees are active to prevent cross-boundary contamination
 - `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
+- Destroying another agent's worktree -- even with `--force`. If you did not create it, do not destroy it. Period.
 
 ## 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.
 
+### Recommended: use `caws worktree merge`
+
+The `merge` command handles the full sequence (conflict check, destroy, merge, cleanup):
+
+```bash
+# Preview conflicts before merging
+caws worktree merge <name> --dry-run
+
+# Merge (destroys worktree, merges branch, deletes branch)
+caws worktree merge <name>
+
+# Merge with custom commit message
+caws worktree merge <name> --message "merge(worktree): description of changes"
+```
+
+### Manual merge (if you need more control)
+
 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"`
 
+### Conflict resolution during merge
+
+The write guard allows edits on the base branch while a merge is in progress (MERGE_HEAD exists). This lets you resolve merge conflicts without needing to abort and retry. After resolving, commit with the `merge(worktree):` format.
+
+## What the write guard allows on the base branch
+
+Even when worktrees are active, the following edits are allowed on the base branch:
+
+- `.claude/` and `.caws/` configuration files
+- `docs/` directory (documentation changes are benign)
+- Any file while a merge is in progress (conflict resolution)
+
 ## Virtual environment in worktrees
 
 Do NOT create a new virtual environment in your worktree. Use the main repo's venv:
@@ -46,6 +79,5 @@ If your project uses `.caws/scope.json`, the `designatedVenvPath` field specifie
 
 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>`
+3. Merge: `caws worktree merge <name>` (handles destroy + merge + branch cleanup)
+4. Or manually: destroy worktree, then `git merge --no-ff <branch>`, then delete branch

package/templates/.cursor/README.md

@@ -9,7 +9,6 @@ Cursor hooks enable seamless integration between CAWS and the Cursor IDE, provid
 - **Real-time quality validation** as you code
 - **Automatic spec validation** when editing working specs
 - **Scope enforcement** preventing out-of-scope file access
-- **Tool validation** for safe MCP execution
 - **Quality monitoring** after file edits
 
 ## Hook Configuration
@@ -19,7 +18,6 @@ The `hooks.json` file defines when each hook runs:
 ```json
 {
   "beforeShellExecution": ["block-dangerous.sh", "audit.sh"],
-  "beforeMCPExecution": ["audit.sh", "caws-tool-validation.sh"],
   "beforeReadFile": ["scan-secrets.sh", "caws-scope-guard.sh"],
   "afterFileEdit": ["format.sh", "naming-check.sh", "validate-spec.sh", "caws-quality-check.sh", "audit.sh"],
   "beforeSubmitPrompt": ["caws-scope-guard.sh", "audit.sh"],
@@ -43,12 +41,6 @@ The `hooks.json` file defines when each hook runs:
 - **Blocks**: Yes (for out-of-scope file access)
 - **Requires**: `.caws/working-spec.yaml`
 
-#### `caws-tool-validation.sh`
-- **Trigger**: `beforeMCPExecution`
-- **Purpose**: Validates CAWS MCP tool calls for security
-- **Blocks**: Yes (for dangerous operations or invalid waivers)
-- **Validates**: Waiver creation, tool permissions, command safety
-
 ### General Security Hooks
 
 #### `block-dangerous.sh`
@@ -242,7 +234,6 @@ Cursor Hooks ←→ CAWS CLI ←→ VS Code Extension
 
 - **Git Hooks**: `.git/hooks/` for commit/push validation
 - **VS Code Extension**: Rich UI for CAWS operations
-- **MCP Server**: Agent tool integration
 - **CAWS CLI**: Core functionality
 
 ### Data Flow

package/templates/.cursor/hooks/audit.sh

@@ -2,7 +2,7 @@
 # Cursor Hook: Audit Trail
 # 
 # Purpose: Log all Cursor AI events for provenance tracking
-# Event: All (beforeShellExecution, beforeMCPExecution, beforeReadFile, 
+# Event: All (beforeShellExecution, beforeReadFile,
 #        afterFileEdit, beforeSubmitPrompt, stop)
 # 
 # @author @darianrosebrook

package/templates/.cursor/hooks/block-dangerous.sh

@@ -29,6 +29,7 @@ HARD_BLOCKS=(
   "git commit --amend --no-edit" # Can rewrite commit history destructively
   "git reset --hard"            # Can lose uncommitted work and stashed changes
   "git push --force"             # Can overwrite remote repository history
+  "git rebase"                   # Rewrites branch history; blocked while worktrees are active
   "dd if="
   "mkfs"
   "format c:"

package/templates/.cursor/hooks/scan-secrets.sh

@@ -28,14 +28,19 @@ if [[ "$FILE_PATH" =~ \.(pem|key|p12|pfx|cert|crt)$ ]]; then
 fi
 
 # Scan content for common secret patterns
-if echo "$CONTENT" | grep -qiE "(api[_-]?key|secret[_-]?key|password|private[_-]?key|access[_-]?token|bearer\s+[A-Za-z0-9_\-\.]+|AKIA[0-9A-Z]{16})"; then
+# bearer requires 20+ chars to avoid false positives on short tokens in docs
+# AKIA prefix is specific to AWS access keys
+if echo "$CONTENT" | grep -qiE "(api[_-]?key\s*[:=]\s*['\"]?[A-Za-z0-9_\-]{16,}|secret[_-]?key\s*[:=]\s*['\"]?[A-Za-z0-9_\-]{16,}|password\s*[:=]\s*['\"]?[^\s'\"]{8,}|private[_-]?key\s*[:=]|access[_-]?token\s*[:=]\s*['\"]?[A-Za-z0-9_\-]{16,}|[Bb]earer\s+[A-Za-z0-9_\-\.]{20,}|AKIA[0-9A-Z]{16})"; then
   # Don't block, but warn
   echo '{"permission":"allow","userMessage":"⚠️ Warning: Potential secrets detected in file. Ensure they are not committed.","agentMessage":"This file may contain secrets. Use placeholder values or environment variables."}' 2>/dev/null
   exit 0
 fi
 
-# Check for common PII patterns (SSN, credit card, etc.)
-if echo "$CONTENT" | grep -qE "([0-9]{3}-[0-9]{2}-[0-9]{4}|[0-9]{4}[- ]?[0-9]{4}[- ]?[0-9]{4}[- ]?[0-9]{4})"; then
+# Check for common PII patterns (SSN, credit card)
+# SSN: exactly 3-2-4 digit pattern (not inside longer numbers)
+# Credit card: require at least a Luhn-plausible 13-19 digit sequence with separators
+if echo "$CONTENT" | grep -qE "(^|[^0-9])[0-9]{3}-[0-9]{2}-[0-9]{4}($|[^0-9])" || \
+   echo "$CONTENT" | grep -qE "(^|[^0-9])[0-9]{4}[- ][0-9]{4}[- ][0-9]{4}[- ][0-9]{4}($|[^0-9])"; then
   echo '{"permission":"allow","userMessage":"⚠️ Warning: Potential PII detected. Ensure compliance with data protection policies.","agentMessage":"This file may contain PII (SSN, credit card). Use anonymized test data."}' 2>/dev/null
   exit 0
 fi

package/templates/.cursor/hooks.json

@@ -9,14 +9,6 @@
         "command": "./.cursor/hooks/audit.sh"
       }
     ],
-    "beforeMCPExecution": [
-      {
-        "command": "./.cursor/hooks/audit.sh"
-      },
-      {
-        "command": "./.cursor/hooks/caws-tool-validation.sh"
-      }
-    ],
     "beforeReadFile": [
       {
         "command": "./.cursor/hooks/scan-secrets.sh"

package/templates/.vscode/launch.json

@@ -1,18 +1,6 @@
 {
   "version": "0.2.0",
   "configurations": [
-    {
-      "name": "Debug MCP Server",
-      "type": "node",
-      "request": "launch",
-      "program": "${workspaceFolder}/packages/caws-mcp-server/index.js",
-      "args": [],
-      "env": {
-        "NODE_ENV": "development",
-        "CAWS_DEBUG": "true"
-      },
-      "console": "integratedTerminal"
-    },
     {
       "name": "Debug CAWS CLI",
       "type": "node",

package/templates/.cursor/hooks/caws-tool-validation.sh

@@ -1,121 +0,0 @@
-#!/bin/bash
-# CAWS Tool Validation Hook
-# Validates MCP tool calls against CAWS security policies
-# @author @darianrosebrook
-
-set -e
-
-# Read input from Cursor
-INPUT=$(cat)
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
-TOOL_ARGS=$(echo "$INPUT" | jq -r '.arguments // "{}"')
-
-# Only validate CAWS-related tools
-if [[ "$TOOL_NAME" =~ ^caws_ ]]; then
-
-  echo "🔍 Validating CAWS tool call: $TOOL_NAME" >&2
-
-  # Check if CAWS CLI is available
-  if ! command -v caws &> /dev/null; then
-    echo '{
-      "userMessage": "❌ CAWS CLI not available",
-      "agentMessage": "Cannot execute CAWS tools - CLI not installed",
-      "block": true,
-      "suggestions": [
-        "Install CAWS CLI: npm install -g @caws/cli",
-        "Check PATH includes CAWS CLI"
-      ]
-    }'
-    exit 1
-  fi
-
-  # Check if we're in a CAWS project
-  if [[ ! -f ".caws/working-spec.yaml" ]]; then
-    echo '{
-      "userMessage": "⚠️ Not in a CAWS project",
-      "agentMessage": "CAWS tools require .caws/working-spec.yaml",
-      "suggestions": [
-        "Initialize CAWS project: caws init",
-        "Create working spec: caws scaffold"
-      ]
-    }'
-  fi
-
-  # Validate tool-specific arguments
-  case "$TOOL_NAME" in
-    "caws_waiver_create")
-      # Check waiver creation permissions
-      IMPACT_LEVEL=$(echo "$TOOL_ARGS" | jq -r '.impactLevel // "low"')
-
-      if [[ "$IMPACT_LEVEL" == "critical" ]]; then
-        echo '{
-          "userMessage": "🚨 Critical waiver requires approval",
-          "agentMessage": "Critical impact waivers need human approval",
-          "block": false,
-          "warnings": [
-            "Critical waivers require code owner review",
-            "Waiver will be flagged for manual approval"
-          ]
-        }'
-      fi
-
-      # Check expiration time
-      EXPIRES_AT=$(echo "$TOOL_ARGS" | jq -r '.expiresAt // ""')
-      if [[ -n "$EXPIRES_AT" ]]; then
-        EXPIRE_TIME=$(date -j -f "%Y-%m-%dT%H:%M:%S%Z" "$EXPIRES_AT" +%s 2>/dev/null || echo "")
-        CURRENT_TIME=$(date +%s)
-        DAYS_DIFF=$(( (EXPIRE_TIME - CURRENT_TIME) / 86400 ))
-
-        if [[ $DAYS_DIFF -gt 90 ]]; then
-          echo '{
-            "userMessage": "⚠️ Waiver expiration too far in future",
-            "agentMessage": "Waivers cannot exceed 90 days expiration",
-            "suggestions": [
-              "Reduce expiration time to within 90 days",
-              "Consider shorter waiver periods for better security"
-            ]
-          }'
-        fi
-      fi
-      ;;
-
-    "caws_evaluate"|"caws_iterate")
-      # These are generally safe to run
-      echo '{"userMessage": "✅ CAWS quality tool validated", "agentMessage": "Tool execution approved"}'
-      ;;
-
-    *)
-      # Unknown CAWS tool - allow but warn
-      echo '{
-        "userMessage": "⚠️ Unknown CAWS tool",
-        "agentMessage": "Tool '"'"$TOOL_NAME"'"' not recognized - proceeding with caution",
-        "suggestions": [
-          "Verify tool name and arguments",
-          "Check CAWS CLI documentation"
-        ]
-      }'
-      ;;
-  esac
-
-elif [[ "$TOOL_NAME" =~ (exec|shell|run|terminal) ]]; then
-  # Generic shell execution - check for dangerous commands
-  COMMAND=$(echo "$TOOL_ARGS" | jq -r '.command // .cmd // ""')
-
-  DANGEROUS_COMMANDS=("rm -rf" "rm -rf /" "format" "mkfs" "dd" "fdisk" ">" "sudo" "chmod 777")
-
-  for dangerous in "${DANGEROUS_COMMANDS[@]}"; do
-    if [[ "$COMMAND" =~ $dangerous ]]; then
-      echo '{
-        "userMessage": "🚫 Dangerous command blocked",
-        "agentMessage": "Command contains dangerous operations: '"'"$dangerous"'"'",
-        "block": true,
-        "suggestions": [
-          "Avoid destructive operations",
-          "Use safer alternatives",
-          "Get explicit approval for dangerous commands"
-        ]
-      }'
-      exit 1
-    fi
-  done
-fi