@paths.design/caws-cli 10.2.0 → 11.1.0

package/templates/.claude/hooks/doc-frontmatter-check.sh

@@ -1,173 +0,0 @@
-#!/bin/bash
-# Document Frontmatter Check Hook for Claude Code
-# Warns when docs/**/*.md files are written/edited without proper frontmatter.
-# Advisory only — does not block.
-#
-# Validates YAML frontmatter with required fields, authority/status enums,
-# governs requirements for high-authority docs, and verified_at_commit for
-# implementation-state claims.
-
-set -euo pipefail
-
-INPUT=$(cat)
-
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
-
-# Only check Write and Edit tools
-if [[ "$TOOL_NAME" != "Write" ]] && [[ "$TOOL_NAME" != "Edit" ]]; then
-  exit 0
-fi
-
-if [[ -z "$FILE_PATH" ]]; then
-  exit 0
-fi
-
-# Only check .md files under docs/
-if [[ ! "$FILE_PATH" =~ docs/.*\.md$ ]]; then
-  exit 0
-fi
-
-# Skip exempt filenames
-BASENAME=$(basename "$FILE_PATH")
-if [[ "$BASENAME" == "README.md" ]] || [[ "$BASENAME" == "INDEX.md" ]] || [[ "$BASENAME" == "index.md" ]] || [[ "$BASENAME" == "00_INDEX.md" ]]; then
-  exit 0
-fi
-
-# Skip archive and templates directories
-if [[ "$FILE_PATH" =~ docs/archive/ ]] || [[ "$FILE_PATH" =~ docs/templates/ ]]; then
-  exit 0
-fi
-
-# Skip ephemeral (gitignored, not governed)
-if [[ "$FILE_PATH" =~ docs/ephemeral/ ]]; then
-  exit 0
-fi
-
-# Check if file exists (Write creates it, Edit modifies it)
-if [[ ! -f "$FILE_PATH" ]]; then
-  exit 0
-fi
-
-# --- Frontmatter validation ---
-
-# V1: Check for frontmatter delimiters
-FIRST_LINE=$(head -1 "$FILE_PATH" 2>/dev/null || echo "")
-if [[ "$FIRST_LINE" != "---" ]]; then
-  echo '{
-    "hookSpecificOutput": {
-      "hookEventName": "PostToolUse",
-      "additionalContext": "Doc governance (V1): '"$FILE_PATH"' is missing YAML frontmatter. All docs under docs/ (except README.md, archive/, templates/) must start with --- delimiters containing doc_id, authority, status, title, owner, and updated fields."
-    }
-  }'
-  exit 0
-fi
-
-# Extract frontmatter block (between first and second ---)
-FRONTMATTER=$(awk 'NR==1 && /^---$/{found=1; next} found && /^---$/{exit} found{print}' "$FILE_PATH")
-
-if [[ -z "$FRONTMATTER" ]]; then
-  echo '{
-    "hookSpecificOutput": {
-      "hookEventName": "PostToolUse",
-      "additionalContext": "Doc governance (V1): '"$FILE_PATH"' has opening --- but no closing --- for frontmatter block."
-    }
-  }'
-  exit 0
-fi
-
-# V2: Check required fields
-MISSING=""
-for field in doc_id authority status title owner updated; do
-  if ! echo "$FRONTMATTER" | grep -q "^${field}:"; then
-    MISSING="${MISSING} ${field}"
-  fi
-done
-
-if [[ -n "$MISSING" ]]; then
-  echo '{
-    "hookSpecificOutput": {
-      "hookEventName": "PostToolUse",
-      "additionalContext": "Doc governance (V2): '"$FILE_PATH"' is missing required frontmatter fields:'"$MISSING"'."
-    }
-  }'
-  exit 0
-fi
-
-# V2: Check authority value
-AUTHORITY=$(echo "$FRONTMATTER" | grep "^authority:" | head -1 | sed 's/^authority: *//' | tr -d '"' | tr -d "'")
-case "$AUTHORITY" in
-  canonical|policy|architecture|adr|spec|roadmap|reference|working|ephemeral)
-    ;;
-  *)
-    echo '{
-      "hookSpecificOutput": {
-        "hookEventName": "PostToolUse",
-        "additionalContext": "Doc governance (V2): '"$FILE_PATH"' has invalid authority '"'"''"$AUTHORITY"''"'"'. Must be one of: canonical, policy, architecture, adr, spec, roadmap, reference, working, ephemeral."
-      }
-    }'
-    exit 0
-    ;;
-esac
-
-# V2: Check status value
-STATUS=$(echo "$FRONTMATTER" | grep "^status:" | head -1 | sed 's/^status: *//' | tr -d '"' | tr -d "'")
-case "$STATUS" in
-  draft|active|implemented|proven|superseded|archived)
-    ;;
-  *)
-    echo '{
-      "hookSpecificOutput": {
-        "hookEventName": "PostToolUse",
-        "additionalContext": "Doc governance (V2): '"$FILE_PATH"' has invalid status '"'"''"$STATUS"''"'"'. Must be one of: draft, active, implemented, proven, superseded, archived."
-      }
-    }'
-    exit 0
-    ;;
-esac
-
-# V3: Check governs for high-authority docs
-case "$AUTHORITY" in
-  canonical|architecture|adr|spec)
-    if ! echo "$FRONTMATTER" | grep -q "^governs:"; then
-      echo '{
-        "hookSpecificOutput": {
-          "hookEventName": "PostToolUse",
-          "additionalContext": "Doc governance (V3): '"$FILE_PATH"' has authority '"'"''"$AUTHORITY"''"'"' but no governs section. Docs with authority canonical/architecture/adr/spec must declare what they govern (modules, schemas, or specs)."
-        }
-      }'
-      exit 0
-    fi
-    ;;
-esac
-
-# V4: Check verified_at_commit for implementation-state claims
-case "$STATUS" in
-  implemented|proven)
-    if ! echo "$FRONTMATTER" | grep -q "^verified_at_commit:"; then
-      echo '{
-        "hookSpecificOutput": {
-          "hookEventName": "PostToolUse",
-          "additionalContext": "Doc governance (V4): '"$FILE_PATH"' has status '"'"''"$STATUS"''"'"' but no verified_at_commit. Docs claiming implementation state must declare the commit SHA where claims were verified."
-        }
-      }'
-      exit 0
-    fi
-    ;;
-esac
-
-# V5: Check superseded_by for superseded docs
-if [[ "$STATUS" == "superseded" ]]; then
-  if ! echo "$FRONTMATTER" | grep -q "^superseded_by:"; then
-    echo '{
-      "hookSpecificOutput": {
-        "hookEventName": "PostToolUse",
-        "additionalContext": "Doc governance (V5): '"$FILE_PATH"' has status '"'"'superseded'"'"' but no superseded_by. Superseded docs must declare their replacement doc_id."
-      }
-    }'
-    exit 0
-  fi
-fi
-
-# All checks passed
-exit 0

package/templates/.claude/hooks/lite-sprawl-check.sh

@@ -1,145 +0,0 @@
-#!/bin/bash
-# CAWS Lite-Mode Sprawl Check Hook
-# Checks for file sprawl patterns (banned names, venv dirs, doc sprawl)
-# @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 operations (new file creation)
-if [[ "$TOOL_NAME" != "Write" ]]; then
-  exit 0
-fi
-
-if [[ -z "$FILE_PATH" ]]; then
-  exit 0
-fi
-
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
-SCOPE_FILE="$PROJECT_DIR/.caws/scope.json"
-
-# Only active in lite mode (scope.json present, no working-spec.yaml)
-if [[ ! -f "$SCOPE_FILE" ]]; then
-  exit 0
-fi
-
-# Get relative path
-# Get relative path (portable — macOS realpath lacks --relative-to)
-if [[ "$FILE_PATH" == "$PROJECT_DIR"/* ]]; then
-  REL_PATH="${FILE_PATH#$PROJECT_DIR/}"
-else
-  REL_PATH="$FILE_PATH"
-fi
-BASENAME=$(basename "$REL_PATH")
-
-# Use Node.js to check banned patterns
-if command -v node >/dev/null 2>&1; then
-  SPRAWL_CHECK=$(node -e "
-    const fs = require('fs');
-    const path = require('path');
-    try {
-      const scope = JSON.parse(fs.readFileSync('$SCOPE_FILE', 'utf8'));
-      const filePath = '$REL_PATH';
-      const basename = '$BASENAME';
-      const banned = scope.bannedPatterns || {};
-
-      function globToRegex(pattern) {
-        let i = 0, re = '';
-        while (i < pattern.length) {
-          const c = pattern[i];
-          if (c === '*' && pattern[i+1] === '*') {
-            re += '.*'; i += 2;
-            if (pattern[i] === '/') i++;
-          } else if (c === '*') {
-            re += '[^/]*'; i++;
-          } else if (c === '?') {
-            re += '[^/]'; i++;
-          } else if (c === '[') {
-            const end = pattern.indexOf(']', i);
-            if (end > i) { re += pattern.slice(i, end + 1); i = end + 1; }
-            else { re += '\\\\['; i++; }
-          } else if (c === '{') {
-            const end = pattern.indexOf('}', i);
-            if (end > i) {
-              const alts = pattern.slice(i + 1, end).split(',').map(a => a.trim());
-              re += '(?:' + alts.join('|') + ')'; i = end + 1;
-            } else { re += '\\\\{'; i++; }
-          } else if ('.+^$|()'.includes(c)) {
-            re += '\\\\' + c; i++;
-          } else {
-            re += c; i++;
-          }
-        }
-        return new RegExp('^' + re + '$');
-      }
-      function matchGlob(str, pattern) {
-        return globToRegex(pattern).test(str);
-      }
-
-      // Check banned file patterns
-      for (const p of (banned.files || [])) {
-        if (matchGlob(basename, p)) {
-          console.log('banned_file:' + p);
-          process.exit(0);
-        }
-      }
-
-      // Check banned doc patterns
-      for (const p of (banned.docs || [])) {
-        if (matchGlob(basename, p)) {
-          console.log('banned_doc:' + p);
-          process.exit(0);
-        }
-      }
-
-      // Check banned directory patterns
-      const parts = filePath.split('/');
-      for (const part of parts) {
-        for (const p of (banned.directories || [])) {
-          if (matchGlob(part, p)) {
-            console.log('banned_dir:' + p + ':' + part);
-            process.exit(0);
-          }
-        }
-      }
-
-      console.log('ok');
-    } catch (error) {
-      console.log('error:' + error.message);
-    }
-  " 2>&1)
-
-  if [[ "$SPRAWL_CHECK" == banned_file:* ]]; then
-    PATTERN="${SPRAWL_CHECK#banned_file:}"
-    echo "BLOCKED: File name matches banned sprawl pattern: $PATTERN" >&2
-    echo "File: $REL_PATH" >&2
-    echo "Banned patterns prevent shadow files like *-enhanced.*, *-final.*, *-v2.*, *-copy.*" >&2
-    echo "Instead, modify the original file directly." >&2
-    exit 2
-  fi
-
-  if [[ "$SPRAWL_CHECK" == banned_doc:* ]]; then
-    PATTERN="${SPRAWL_CHECK#banned_doc:}"
-    echo "BLOCKED: Doc file matches banned sprawl pattern: $PATTERN" >&2
-    echo "File: $REL_PATH" >&2
-    echo "Avoid creating many summary/recap/plan files. Update existing documentation instead." >&2
-    exit 2
-  fi
-
-  if [[ "$SPRAWL_CHECK" == banned_dir:* ]]; then
-    IFS=':' read -r _ PATTERN DIR_NAME <<< "$SPRAWL_CHECK"
-    echo "BLOCKED: Directory matches banned pattern: $PATTERN (directory: $DIR_NAME)" >&2
-    echo "File: $REL_PATH" >&2
-    echo "Use the designated venv path instead of creating new virtual environments." >&2
-    exit 2
-  fi
-fi
-
-# Allow the operation
-exit 0

package/templates/.claude/hooks/naming-check.sh

@@ -1,100 +0,0 @@
-#!/bin/bash
-# CAWS Naming Convention Check Hook for Claude Code
-# Validates file naming against CAWS conventions
-# @author @darianrosebrook
-
-set -euo pipefail
-
-# Read JSON input from Claude Code
-INPUT=$(cat)
-
-# Extract file path from PostToolUse input
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
-
-# Only check Write tool (new files)
-if [[ "$TOOL_NAME" != "Write" ]]; then
-  exit 0
-fi
-
-if [[ -z "$FILE_PATH" ]]; then
-  exit 0
-fi
-
-# Get filename
-FILENAME=$(basename "$FILE_PATH")
-
-# Banned modifiers that indicate incomplete/temporary naming
-BANNED_MODIFIERS=(
-  "enhanced"
-  "unified"
-  "simplified"
-  "better"
-  "new"
-  "next"
-  "final"
-  "copy"
-  "revamp"
-  "improved"
-  "alt"
-  "tmp"
-  "scratch"
-  "wip"
-  "test-"
-  "-test"
-  "_test"
-  "temp"
-  "old"
-  "backup"
-)
-
-# Convert filename to lowercase for checking
-FILENAME_LOWER=$(echo "$FILENAME" | tr '[:upper:]' '[:lower:]')
-
-# Check for banned modifiers (word-boundary aware)
-for modifier in "${BANNED_MODIFIERS[@]}"; do
-  # Match modifier preceded by start-of-string, hyphen, underscore, or dot
-  # and followed by end-of-string, hyphen, underscore, or dot
-  # Prevents false positives like "old" in "gold_oracle" or "new" in "renewable"
-  if [[ "$FILENAME_LOWER" =~ (^|[-_.])"$modifier"([-_.]|$) ]]; then
-    # Special case: allow test files that follow conventions
-    if [[ "$modifier" == "test-" ]] || [[ "$modifier" == "-test" ]] || [[ "$modifier" == "_test" ]]; then
-      if [[ "$FILENAME_LOWER" =~ \.(test|spec)\.(js|ts|jsx|tsx|py|go|rs)$ ]]; then
-        continue
-      fi
-    fi
-
-    echo '{
-      "hookSpecificOutput": {
-        "hookEventName": "PostToolUse",
-        "additionalContext": "Warning: The filename '\'''"$FILENAME"''\'' contains the modifier '\'''"$modifier"''\'' which may indicate temporary or non-canonical naming. Consider using a more descriptive, permanent name. See CAWS naming conventions in .caws/canonical-map.yaml or run '\''caws naming check'\''."
-      }
-    }'
-    exit 0
-  fi
-done
-
-# Check for version suffixes (e.g., file-v2.js, file_v3.ts)
-if [[ "$FILENAME_LOWER" =~ [-_]v[0-9]+\. ]]; then
-  echo '{
-    "hookSpecificOutput": {
-      "hookEventName": "PostToolUse",
-      "additionalContext": "Warning: The filename '\'''"$FILENAME"''\'' contains a version suffix. Version control should be handled by git, not file names. Consider removing the version suffix."
-    }
-  }'
-  exit 0
-fi
-
-# Check for date stamps (e.g., file-2024-01-15.js)
-if [[ "$FILENAME_LOWER" =~ [0-9]{4}[-_][0-9]{2}[-_][0-9]{2} ]]; then
-  echo '{
-    "hookSpecificOutput": {
-      "hookEventName": "PostToolUse",
-      "additionalContext": "Warning: The filename '\'''"$FILENAME"''\'' contains a date stamp. Version control should be handled by git, not file names. Consider removing the date."
-    }
-  }'
-  exit 0
-fi
-
-# File naming is OK
-exit 0

package/templates/.claude/hooks/protected-paths.sh

@@ -1,39 +0,0 @@
-#!/bin/bash
-# CAWS Protected Paths Guard for Claude Code
-# Blocks direct Write/Edit access to guard code and guard state.
-# @author @darianrosebrook
-
-set -euo pipefail
-
-INPUT=$(cat)
-
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
-
-case "$TOOL_NAME" in
-  Write|Edit) ;;
-  *) exit 0 ;;
-esac
-
-if [[ -z "$FILE_PATH" ]]; then
-  exit 0
-fi
-
-# If you are reading this because a write was blocked, do not edit hook files or
-# strike-state files to bypass a guard. Switch into the correct worktree, fix the
-# active spec scope, or ask the user if the guard itself is wrong.
-case "$FILE_PATH" in
-  */.claude/hooks/*)
-    echo "BLOCKED: $FILE_PATH is protected." >&2
-    echo "Ask the user for permission before editing Claude hook scripts." >&2
-    exit 1
-    ;;
-  */.claude/logs/guard-strikes-*.json)
-    echo "BLOCKED: $FILE_PATH is protected guard state." >&2
-    echo "Do not reset or edit strike counters to bypass enforcement." >&2
-    echo "Switch into the correct worktree, update the active CAWS spec scope, or ask the user for direction instead." >&2
-    exit 2
-    ;;
-esac
-
-exit 0

package/templates/.claude/hooks/quality-check.sh

@@ -1,81 +0,0 @@
-#!/bin/bash
-# CAWS Quality Check Hook for Claude Code
-# Runs CAWS quality validation after file edits
-# @author @darianrosebrook
-
-set -euo pipefail
-
-# Read JSON input from Claude Code
-INPUT=$(cat)
-
-# Extract file info from PostToolUse input
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
-
-# Only run on Write/Edit of source files
-if [[ "$TOOL_NAME" != "Write" ]] && [[ "$TOOL_NAME" != "Edit" ]]; then
-  exit 0
-fi
-
-# Skip non-source files and node_modules/dist
-if [[ ! "$FILE_PATH" =~ \.(js|ts|jsx|tsx|py|go|rs|java|mjs|cjs)$ ]] || \
-   [[ "$FILE_PATH" =~ node_modules ]] || \
-   [[ "$FILE_PATH" =~ dist/ ]] || \
-   [[ "$FILE_PATH" =~ build/ ]]; then
-  exit 0
-fi
-
-# Determine project directory
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
-
-# Check if we're in a CAWS project
-if [[ ! -f "$PROJECT_DIR/.caws/working-spec.yaml" ]] && [[ ! -d "$PROJECT_DIR/.caws/specs" ]]; then
-  exit 0
-fi
-
-# Check if CAWS CLI is available
-if ! command -v caws &> /dev/null; then
-  echo '{
-    "hookSpecificOutput": {
-      "hookEventName": "PostToolUse",
-      "additionalContext": "CAWS CLI not available. Consider installing with: npm install -g @paths.design/caws-cli"
-    }
-  }'
-  exit 0
-fi
-
-# Run quality gates via the unified pipeline
-RESULT=$(caws gates run --context=edit --file "$FILE_PATH" --json --quiet 2>&1) || GATE_EXIT=$?
-
-if [ -z "$RESULT" ]; then
-  # No output — gates command not available or errored
-  echo '{
-    "hookSpecificOutput": {
-      "hookEventName": "PostToolUse",
-      "additionalContext": "Quality gates did not produce output (exit '"${GATE_EXIT:-0}"'). Run '\''caws gates run'\'' for details."
-    }
-  }'
-  exit 0
-fi
-
-# Check if gates passed
-PASSED=$(echo "$RESULT" | jq -r '.passed // true' 2>/dev/null)
-
-if [ "$PASSED" = "true" ]; then
-  echo '{
-    "hookSpecificOutput": {
-      "hookEventName": "PostToolUse",
-      "additionalContext": "Quality gates passed for this change."
-    }
-  }'
-else
-  # Extract top 3 gate failure messages
-  VIOLATIONS=$(echo "$RESULT" | jq -r '[.gates[] | select(.status == "fail") | "- \(.name): \(.messages[0] // "failed")"] | .[0:3] | .[]' 2>/dev/null || echo "Run 'caws gates run' for details")
-
-  echo '{
-    "decision": "block",
-    "reason": "Quality gate violations detected. Please address the following issues before continuing:\n'"$VIOLATIONS"'\n\nRun '\''caws gates run'\'' for full details."
-  }'
-fi
-
-exit 0

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

@@ -1,85 +0,0 @@
-#!/bin/bash
-# CAWS Secret Scanner for Claude Code
-# Warns when reading files that may contain secrets
-# @author @darianrosebrook
-
-set -euo pipefail
-
-# Read JSON input from Claude Code
-INPUT=$(cat)
-
-# Extract file path
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
-
-if [[ -z "$FILE_PATH" ]]; then
-  exit 0
-fi
-
-# Get just the filename for pattern matching
-FILENAME=$(basename "$FILE_PATH")
-
-# Files that commonly contain secrets
-SECRET_FILE_PATTERNS=(
-  '.env'
-  '.env.local'
-  '.env.production'
-  '.env.development'
-  '.env.*'
-  'credentials.json'
-  'service-account.json'
-  'secrets.yaml'
-  'secrets.yml'
-  'secrets.json'
-  '.netrc'
-  '.npmrc'
-  '.pypirc'
-  'id_rsa'
-  'id_ed25519'
-  'id_ecdsa'
-  '*.pem'
-  '*.key'
-  '*.p12'
-  '*.pfx'
-  'htpasswd'
-  'shadow'
-)
-
-# Directories that commonly contain secrets
-SECRET_DIRS=(
-  '.ssh'
-  '.aws'
-  '.azure'
-  '.gcloud'
-  '.kube'
-  '.gnupg'
-)
-
-# Check if file matches secret patterns
-for pattern in "${SECRET_FILE_PATTERNS[@]}"; do
-  if [[ "$FILENAME" == $pattern ]]; then
-    # Output JSON with warning for Claude
-    echo '{
-      "hookSpecificOutput": {
-        "hookEventName": "PreToolUse",
-        "additionalContext": "WARNING: This file may contain secrets. Do not include sensitive values in your response. If you need to reference credentials, use placeholders like <API_KEY> instead of actual values."
-      }
-    }'
-    exit 0
-  fi
-done
-
-# Check if file is in a sensitive directory
-for dir in "${SECRET_DIRS[@]}"; do
-  if [[ "$FILE_PATH" == *"/$dir/"* ]] || [[ "$FILE_PATH" == *"/$dir" ]]; then
-    echo '{
-      "hookSpecificOutput": {
-        "hookEventName": "PreToolUse",
-        "additionalContext": "WARNING: This file is in a sensitive directory that may contain secrets. Do not include any sensitive values in your response."
-      }
-    }'
-    exit 0
-  fi
-done
-
-# Allow the read
-exit 0