@paths.design/caws-cli 10.2.0 → 11.1.0

package/templates/.claude/README.md

@@ -1,190 +0,0 @@
-# Claude Code Integration for CAWS
-
-This directory contains Claude Code hooks and configuration for CAWS (Coding Agent Working Standard) integration.
-
-## Overview
-
-CAWS hooks for Claude Code provide:
-
-- **Safety Gates**: Block dangerous commands and scan for secrets
-- **Quality Gates**: Run CAWS quality checks after file edits
-- **Scope Guards**: Validate edits against the working spec's scope
-- **Audit Logging**: Track agent actions for compliance
-
-## Directory Structure
-
-```
-.claude/
-├── settings.json      # Claude Code settings with hooks configuration
-├── hooks/             # Hook scripts
-│   ├── audit.sh           # Session and action logging
-│   ├── block-dangerous.sh # Block destructive commands
-│   ├── scan-secrets.sh    # Warn when reading sensitive files
-│   ├── quality-check.sh   # Run CAWS quality gates
-│   ├── validate-spec.sh   # Validate spec files
-│   ├── scope-guard.sh     # Check scope boundaries
-│   └── naming-check.sh    # Validate file naming conventions
-├── logs/              # Audit logs (gitignored)
-└── README.md          # This file
-```
-
-## Hook Events
-
-### PreToolUse Hooks
-
-Run before Claude executes a tool:
-
-| Hook | Matcher | Purpose |
-|------|---------|---------|
-| `block-dangerous.sh` | `Bash` | Block destructive shell commands |
-| `scan-secrets.sh` | `Read` | Warn when reading sensitive files |
-| `scope-guard.sh` | `Write\|Edit` | Check scope boundaries before edits (use `caws scope show` to diagnose blocks) |
-
-### PostToolUse Hooks
-
-Run after Claude executes a tool:
-
-| Hook | Matcher | Purpose |
-|------|---------|---------|
-| `quality-check.sh` | `Write\|Edit` | Run CAWS quality gates |
-| `validate-spec.sh` | `Write\|Edit` | Validate spec file changes |
-| `naming-check.sh` | `Write` | Check file naming conventions |
-| `audit.sh` | `Write\|Edit\|Bash` | Log tool usage |
-
-### Session Hooks
-
-| Hook | Event | Purpose |
-|------|-------|---------|
-| `audit.sh session-start` | `SessionStart` | Log session start |
-| `audit.sh stop` | `Stop` | Log session end |
-
-## Configuration
-
-### Enable/Disable Hooks
-
-Edit `settings.json` to enable or disable specific hooks. Remove entries from the `hooks` object to disable them.
-
-### Hook Levels
-
-The scaffold supports four hook levels:
-
-- **safety**: Block dangerous commands, scan for secrets
-- **quality**: Run quality gates on file edits
-- **scope**: Validate edits against spec scope
-- **audit**: Log all agent actions
-
-Run `caws init --hooks=safety,quality` to enable specific levels.
-
-## Audit Logs
-
-Audit logs are written to `.claude/logs/`:
-
-- `audit.log` - All-time log (appended)
-- `audit-YYYY-MM-DD.log` - Daily logs
-
-Logs are JSON-formatted for easy parsing:
-
-```json
-{
-  "timestamp": "2024-01-15T10:30:00Z",
-  "session_id": "abc123",
-  "event": "tool_use",
-  "tool": "Write",
-  "file": "src/index.ts",
-  "cwd": "/project"
-}
-```
-
-## Customization
-
-### Adding Custom Hooks
-
-1. Create a new script in `.claude/hooks/`
-2. Make it executable: `chmod +x .claude/hooks/my-hook.sh`
-3. Add it to `settings.json`:
-
-```json
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/my-hook.sh",
-            "timeout": 10
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### Hook Input/Output
-
-Hooks receive JSON input via stdin:
-
-```json
-{
-  "session_id": "abc123",
-  "hook_event_name": "PostToolUse",
-  "tool_name": "Write",
-  "tool_input": {
-    "file_path": "/path/to/file.ts",
-    "content": "..."
-  },
-  "tool_response": { "success": true }
-}
-```
-
-Hooks can output JSON to control Claude's behavior:
-
-```json
-{
-  "decision": "block",
-  "reason": "Quality gate failed: ..."
-}
-```
-
-Or add context:
-
-```json
-{
-  "hookSpecificOutput": {
-    "hookEventName": "PostToolUse",
-    "additionalContext": "Remember to update the tests."
-  }
-}
-```
-
-## Troubleshooting
-
-### Hooks Not Running
-
-1. Check `settings.json` syntax: `cat .claude/settings.json | jq .`
-2. Verify scripts are executable: `ls -la .claude/hooks/`
-3. Test hooks manually: `echo '{}' | .claude/hooks/audit.sh`
-
-### Permission Errors
-
-Make all hook scripts executable:
-
-```bash
-chmod +x .claude/hooks/*.sh
-```
-
-### Debug Hooks
-
-Run Claude Code with `--debug` to see hook execution details:
-
-```bash
-claude --debug
-```
-
-## Further Reading
-
-- [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks)
-- [CAWS Quality Gates](../../docs/quality-gates.md)
-- [CAWS Scope Management](../../docs/scope-management.md)

package/templates/.claude/hooks/audit.sh

@@ -1,121 +0,0 @@
-#!/bin/bash
-# CAWS Audit Hook for Claude Code
-# Logs agent actions for compliance and debugging
-# @author @darianrosebrook
-
-set -euo pipefail
-
-# Get event type from argument or input
-EVENT_TYPE="${1:-tool-use}"
-
-# Read JSON input from stdin
-INPUT=$(cat)
-
-# Parse common fields from Claude Code hook input
-SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
-CWD=$(echo "$INPUT" | jq -r '.cwd // "."')
-HOOK_EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // "unknown"')
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
-PERMISSION_MODE=$(echo "$INPUT" | jq -r '.permission_mode // "default"')
-
-# Ensure log directory exists
-LOG_DIR="${CLAUDE_PROJECT_DIR:-.}/.claude/logs"
-mkdir -p "$LOG_DIR"
-
-# Log file path
-LOG_FILE="$LOG_DIR/audit.log"
-DATE_LOG_FILE="$LOG_DIR/audit-$(date +%Y-%m-%d).log"
-
-# Timestamp
-TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-
-# Build log entry based on event type
-case "$EVENT_TYPE" in
-  session-start)
-    SOURCE=$(echo "$INPUT" | jq -r '.source // "unknown"')
-    MODEL=$(echo "$INPUT" | jq -r '.model // "unknown"')
-    LOG_ENTRY=$(jq -n \
-      --arg ts "$TIMESTAMP" \
-      --arg sid "$SESSION_ID" \
-      --arg event "session_start" \
-      --arg source "$SOURCE" \
-      --arg model "$MODEL" \
-      --arg cwd "$CWD" \
-      '{timestamp: $ts, session_id: $sid, event: $event, source: $source, model: $model, cwd: $cwd}')
-    ;;
-
-  stop)
-    STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
-    LOG_ENTRY=$(jq -n \
-      --arg ts "$TIMESTAMP" \
-      --arg sid "$SESSION_ID" \
-      --arg event "session_stop" \
-      --arg cwd "$CWD" \
-      --argjson hook_active "$STOP_HOOK_ACTIVE" \
-      '{timestamp: $ts, session_id: $sid, event: $event, cwd: $cwd, stop_hook_active: $hook_active}')
-    ;;
-
-  tool-use)
-    # Extract tool-specific info
-    TOOL_INPUT=$(echo "$INPUT" | jq -c '.tool_input // {}')
-    TOOL_RESPONSE=$(echo "$INPUT" | jq -c '.tool_response // {}')
-    TOOL_USE_ID=$(echo "$INPUT" | jq -r '.tool_use_id // ""')
-
-    # For file operations, extract the path
-    FILE_PATH=$(echo "$TOOL_INPUT" | jq -r '.file_path // ""')
-    COMMAND=$(echo "$TOOL_INPUT" | jq -r '.command // ""')
-
-    LOG_ENTRY=$(jq -n \
-      --arg ts "$TIMESTAMP" \
-      --arg sid "$SESSION_ID" \
-      --arg event "tool_use" \
-      --arg tool "$TOOL_NAME" \
-      --arg file "$FILE_PATH" \
-      --arg cmd "$COMMAND" \
-      --arg cwd "$CWD" \
-      --arg mode "$PERMISSION_MODE" \
-      '{timestamp: $ts, session_id: $sid, event: $event, tool: $tool, file: $file, command: $cmd, cwd: $cwd, permission_mode: $mode}')
-    ;;
-
-  *)
-    LOG_ENTRY=$(jq -n \
-      --arg ts "$TIMESTAMP" \
-      --arg sid "$SESSION_ID" \
-      --arg event "$EVENT_TYPE" \
-      --arg hook "$HOOK_EVENT" \
-      --arg cwd "$CWD" \
-      '{timestamp: $ts, session_id: $sid, event: $event, hook_event: $hook, cwd: $cwd}')
-    ;;
-esac
-
-# --- Log rotation ---
-# Keep main audit.log under 10MB; keep date-logs for 30 days
-rotate_logs() {
-  # Rotate main audit.log at 10MB
-  if [[ -f "$LOG_FILE" ]]; then
-    local size
-    size=$(wc -c < "$LOG_FILE" 2>/dev/null | tr -d ' ')
-    if [[ "$size" -gt 10485760 ]]; then
-      # Keep last rotated copy, discard older
-      [[ -f "${LOG_FILE}.1" ]] && rm -f "${LOG_FILE}.1"
-      mv "$LOG_FILE" "${LOG_FILE}.1"
-    fi
-  fi
-
-  # Prune date-based logs older than 30 days
-  if [[ -d "$LOG_DIR" ]]; then
-    find "$LOG_DIR" -name 'audit-*.log' -type f -mtime +30 -delete 2>/dev/null || true
-  fi
-}
-
-# Run rotation check ~1% of the time (avoid stat overhead on every tool call)
-if [[ $(( RANDOM % 100 )) -eq 0 ]]; then
-  rotate_logs
-fi
-
-# Append to log files
-echo "$LOG_ENTRY" >> "$LOG_FILE"
-echo "$LOG_ENTRY" >> "$DATE_LOG_FILE"
-
-# Success - allow operation to continue
-exit 0

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

@@ -1,203 +0,0 @@
-#!/bin/bash
-# CAWS Command Safety Gate for Claude Code
-# Delegates to classify_command.py for robust command parsing and classification.
-# Falls back to bash pattern matching if Python is unavailable.
-#
-# The Python classifier handles:
-#   - Heredoc-aware parsing (won't false-positive on quoted dangerous commands)
-#   - Quoted-region stripping (echo "git reset --hard" is safe)
-#   - Pipeline-aware dangers (curl | sh)
-#   - Context-aware rm classification (safe prefixes vs dangerous targets)
-#   - Proper shell segmentation (&&, ||, ;, |)
-#
-# @author @darianrosebrook
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-# Read JSON input from Claude Code
-INPUT=$(cat)
-
-# Extract tool info
-TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""')
-COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // ""')
-
-# Only check Bash tool
-if [[ "$TOOL_NAME" != "Bash" ]] || [[ -z "$COMMAND" ]]; then
-  exit 0
-fi
-
-# --- Try Python classifier first (preferred) ---
-CLASSIFIER="$SCRIPT_DIR/classify_command.py"
-if [[ -f "$CLASSIFIER" ]] && command -v python3 >/dev/null 2>&1; then
-  REPO_ROOT="${CLAUDE_PROJECT_DIR:-.}"
-  CLASSIFIER_STDERR=$(mktemp)
-  RESULT=$(printf '%s' "$COMMAND" | python3 "$CLASSIFIER" \
-    --repo-root "$REPO_ROOT" \
-    --home "$HOME" \
-    --cwd "$(pwd)" 2>"$CLASSIFIER_STDERR") || {
-    DIAG=$(head -c 200 "$CLASSIFIER_STDERR" 2>/dev/null || true)
-    rm -f "$CLASSIFIER_STDERR"
-    RESULT="{\"decision\":\"ask\",\"reason\":\"command classifier failed: ${DIAG:-unknown error}\"}"
-  }
-  rm -f "$CLASSIFIER_STDERR"
-
-  DECISION=$(printf '%s' "$RESULT" | jq -r '.decision // "ask"')
-  REASON=$(printf '%s' "$RESULT" | jq -r '.reason // "unknown"')
-
-  case "$DECISION" in
-    allow)
-      exit 0
-      ;;
-    deny)
-      echo "BLOCKED: $REASON" >&2
-      echo "Command was: $COMMAND" >&2
-      exit 2
-      ;;
-    ask)
-      echo "WARNING: $REASON" >&2
-      echo "Command was: $COMMAND" >&2
-      exit 1
-      ;;
-  esac
-fi
-
-# --- Fallback: bash pattern matching (less precise, no heredoc/quote awareness) ---
-
-DANGEROUS_PATTERNS=(
-  # Destructive file operations
-  'rm -rf /'
-  'rm -rf ~'
-  'rm -rf \*'
-  'rm -rf \.'
-  'rm -rf /\*'
-  'dd if=/dev/zero'
-  'dd if=/dev/random'
-  'mkfs\.'
-  'fdisk'
-  '> /dev/sd'
-
-  # Fork bombs and resource exhaustion
-  ':\(\)\{:\|:\&\};:'
-  'while true.*fork'
-
-  # Credential/secret exposure
-  'cat.*\.env'
-  'cat.*/etc/passwd'
-  'cat.*/etc/shadow'
-  'cat.*id_rsa'
-  'cat.*\.ssh/'
-  'cat.*credentials'
-  'cat.*\.aws/'
-
-  # Network exfiltration
-  'curl.*\|.*sh'
-  'wget.*\|.*sh'
-  'curl.*\|.*bash'
-  'wget.*\|.*bash'
-
-  # Permission escalation
-  'chmod 777'
-  'chmod -R 777'
-  'chmod.*\+s'
-
-  # History manipulation
-  'history -c'
-  'rm.*\.bash_history'
-  'rm.*\.zsh_history'
-
-  # System modification
-  'shutdown'
-  'reboot'
-  'init 0'
-  'init 6'
-
-  # Git destructive operations
-  'git init'
-  'git reset --hard'
-  'git push --force'
-  'git push -f '
-  'git push --force-with-lease'
-  'git clean -f'
-  'git checkout \.'
-  'git restore \.'
-  '(^|&&|\|\||;|\|)\s*git rebase'
-  '(^|&&|\|\||;|\|)\s*git cherry-pick'
-
-  # Virtual environment creation (prevents venv sprawl)
-  'python -m venv'
-  'python3 -m venv'
-  'virtualenv '
-  'conda create'
-)
-
-# Check command against dangerous patterns
-for pattern in "${DANGEROUS_PATTERNS[@]}"; do
-  if echo "$COMMAND" | grep -qiE "$pattern"; then
-    # Allow git init in worktree context
-    if [[ "$pattern" == "git init" ]] && [[ "${CAWS_WORKTREE_CONTEXT:-0}" == "1" ]]; then
-      continue
-    fi
-
-    # Allow git rebase/cherry-pick only when no worktrees are active
-    if [[ "$pattern" == *"git rebase"* ]] || [[ "$pattern" == *"git cherry-pick"* ]]; then
-      PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
-      if command -v git >/dev/null 2>&1; then
-        GIT_COMMON=$(cd "$PROJECT_DIR" && git rev-parse --git-common-dir 2>/dev/null || echo "")
-        if [[ -n "$GIT_COMMON" ]] && [[ "$GIT_COMMON" != ".git" ]]; then
-          CANDIDATE=$(cd "$PROJECT_DIR" && cd "$GIT_COMMON/.." 2>/dev/null && pwd || echo "")
-          if [[ -n "$CANDIDATE" ]] && [[ -d "$CANDIDATE/.caws" ]]; then
-            PROJECT_DIR="$CANDIDATE"
-          fi
-        fi
-      fi
-      WT_FILE="$PROJECT_DIR/.caws/worktrees.json"
-      if [[ -f "$WT_FILE" ]] && command -v node >/dev/null 2>&1; then
-        ACTIVE_COUNT=$(node -e "
-          try {
-            var r = JSON.parse(require('fs').readFileSync('$WT_FILE','utf8'));
-            var c = Object.values(r.worktrees||{}).filter(function(w){return w.status==='active';}).length;
-            console.log(c);
-          } catch(e) { console.log(0); }
-        " 2>/dev/null || echo "0")
-        if [[ "$ACTIVE_COUNT" -gt 0 ]]; then
-          GIT_SUBCMD="git operation"
-          [[ "$pattern" == *"git rebase"* ]] && GIT_SUBCMD="git rebase"
-          [[ "$pattern" == *"git cherry-pick"* ]] && GIT_SUBCMD="git cherry-pick"
-          echo "BLOCKED: $GIT_SUBCMD is forbidden while $ACTIVE_COUNT worktree(s) are active." >&2
-          echo "This can replay or rewrite commits across worktree boundaries." >&2
-          echo "Command was: $COMMAND" >&2
-          exit 2
-        fi
-      fi
-      continue
-    fi
-
-    # Allow venv commands if target matches designated venv path from scope.json
-    if echo "$pattern" | grep -qE '(python.*venv|virtualenv|conda create)'; then
-      PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
-      SCOPE_FILE="$PROJECT_DIR/.caws/scope.json"
-      if [[ -f "$SCOPE_FILE" ]] && command -v node >/dev/null 2>&1; then
-        DESIGNATED_VENV=$(node -e "try { const s = JSON.parse(require('fs').readFileSync('$SCOPE_FILE','utf8')); console.log(s.designatedVenvPath || ''); } catch(e) { console.log(''); }" 2>/dev/null || echo "")
-        if [[ -n "$DESIGNATED_VENV" ]] && echo "$COMMAND" | grep -qF "$DESIGNATED_VENV"; then
-          continue
-        fi
-      fi
-    fi
-
-    echo "BLOCKED: Command matches dangerous pattern: $pattern" >&2
-    echo "Command was: $COMMAND" >&2
-    exit 2
-  fi
-done
-
-# Check for sudo without specific allowed commands
-if echo "$COMMAND" | grep -qE '^sudo\s' && ! echo "$COMMAND" | grep -qE 'sudo (npm|yarn|pnpm|brew|apt-get|apt|dnf|yum)'; then
-  echo "BLOCKED: sudo commands require explicit approval" >&2
-  echo "If this command is safe, please run it manually in your terminal" >&2
-  exit 2
-fi
-
-# Allow the command
-exit 0