@paths.design/caws-cli 9.3.2 → 10.0.1

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

@@ -0,0 +1,173 @@
+#!/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/dist/templates/.claude/hooks/quality-check.sh

@@ -29,25 +29,39 @@ fi
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 
 # Check if we're in a CAWS project
-if [[ ! -f "$PROJECT_DIR/.caws/working-spec.yaml" ]]; then
+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
-  # Suggest installing CAWS
   echo '{
     "hookSpecificOutput": {
       "hookEventName": "PostToolUse",
-      "additionalContext": "CAWS CLI not available. Consider installing with: npm install -g @caws/cli"
+      "additionalContext": "CAWS CLI not available. Consider installing with: npm install -g @paths.design/caws-cli"
     }
   }'
   exit 0
 fi
 
-# Run CAWS quality gates in quiet mode for quick feedback
-if caws quality-gates --context=commit --quiet 2>/dev/null; then
-  # Quality check passed - provide positive feedback
+# 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",
@@ -55,13 +69,12 @@ if caws quality-gates --context=commit --quiet 2>/dev/null; then
     }
   }'
 else
-  # Quality check failed - provide feedback to Claude
-  # Run again to get violations summary
-  VIOLATIONS=$(caws quality-gates --context=commit --json 2>/dev/null | jq -r '.violations[:3] | .[] | "- \(.gate): \(.message)"' 2>/dev/null || echo "Run 'caws quality-gates' for details")
+  # 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 quality-gates'\'' for full details."
+    "reason": "Quality gate violations detected. Please address the following issues before continuing:\n'"$VIOLATIONS"'\n\nRun '\''caws gates run'\'' for full details."
   }'
 fi
 

package/dist/templates/.claude/hooks/scope-guard.sh

@@ -123,27 +123,28 @@ if [[ ! -f "$SPEC_FILE" ]] && [[ -f "$SCOPE_FILE" ]]; then
       }
     " 2>&1)
 
+
+    if [[ "$LITE_CHECK" == error:* ]]; then
+      ERROR_MSG="${LITE_CHECK#error:}"
+      echo "BLOCKED: Scope check failed — cannot verify file is in scope" >&2
+      echo "  Error: $ERROR_MSG" >&2
+      exit 2
+    fi
+
     if [[ "$LITE_CHECK" == banned:* ]]; then
       PATTERN="${LITE_CHECK#banned:}"
-      echo '{
-        "hookSpecificOutput": {
-          "hookEventName": "PreToolUse",
-          "permissionDecision": "ask",
-          "permissionDecisionReason": "This file ('"$REL_PATH"') matches a banned pattern ('"$PATTERN"') in .caws/scope.json. Creating files with this pattern is blocked to prevent file sprawl."
-        }
-      }'
-      exit 0
+      echo "BLOCKED: $REL_PATH matches banned pattern ($PATTERN) in .caws/scope.json"
+      echo "  Scope allows: files not matching banned patterns"
+      echo "  To modify scope, update bannedPatterns in .caws/scope.json"
+      exit 2
     fi
 
     if [[ "$LITE_CHECK" == "not_allowed" ]]; then
-      echo '{
-        "hookSpecificOutput": {
-          "hookEventName": "PreToolUse",
-          "permissionDecision": "ask",
-          "permissionDecisionReason": "This file ('"$REL_PATH"') is outside the allowed directories in .caws/scope.json. Please confirm this edit is intentional."
-        }
-      }'
-      exit 0
+      ALLOWED_DIRS=$(node -e "const s=JSON.parse(require('fs').readFileSync('$SCOPE_FILE','utf8')); console.log((s.allowedDirectories||[]).join(', '))" 2>/dev/null || echo "unknown")
+      echo "BLOCKED: $REL_PATH is outside allowed directories"
+      echo "  Scope allows: $ALLOWED_DIRS"
+      echo "  To modify scope, update allowedDirectories in .caws/scope.json"
+      exit 2
     fi
 
     # File is allowed - exit normally
@@ -270,29 +271,30 @@ if command -v node >/dev/null 2>&1; then
     }
   " 2>&1)
 
+
+  if [[ "$SCOPE_CHECK" == error:* ]]; then
+    ERROR_MSG="${SCOPE_CHECK#error:}"
+    echo "BLOCKED: Scope check failed — cannot verify file is in scope" >&2
+    echo "  Error: $ERROR_MSG" >&2
+    echo "  Fix the spec file or scope configuration before editing files" >&2
+    exit 2
+  fi
+
   if [[ "$SCOPE_CHECK" == out_of_scope:* ]]; then
     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 '"$SOURCE"' (pattern: '"$PATTERN"'). Editing it may cause scope creep. Please confirm this edit is intentional."
-      }
-    }'
-    exit 0
+    echo "BLOCKED: $REL_PATH is excluded by scope.out in $SOURCE (pattern: $PATTERN)"
+    echo "  Scope allows: files not matching scope.out patterns"
+    echo "  To modify scope, update the spec's scope.out field"
+    exit 2
   fi
 
   if [[ "$SCOPE_CHECK" == "not_in_scope" ]]; then
-    echo '{
-      "hookSpecificOutput": {
-        "hookEventName": "PreToolUse",
-        "permissionDecision": "ask",
-        "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
+    echo "BLOCKED: $REL_PATH is not in the defined scope.in of any active spec"
+    echo "  Scope allows: files matching scope.in patterns in active specs"
+    echo "  To modify scope, update the spec's scope.in field"
+    exit 2
   fi
 fi
 

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

@@ -40,7 +40,7 @@ if [ -f "$CAWS_ROOT/.caws/worktrees.json" ] && command -v node >/dev/null 2>&1;
   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'; });
+      var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active' || w.status === 'fresh' || w.status === 'merged'; });
       if (active.length > 0) {
         var names = active.map(function(w) { return w.name + ' (' + w.branch + ')'; });
         console.log(active.length + ':' + names.join(', '));
@@ -58,7 +58,7 @@ if [ -f "$CAWS_ROOT/.caws/worktrees.json" ] && command -v node >/dev/null 2>&1;
     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'; });
+        var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active' || w.status === 'fresh' || w.status === 'merged'; });
         if (active.length > 0) console.log(active[0].baseBranch || '');
         else console.log('');
       } catch(e) { console.log(''); }

package/dist/templates/.claude/hooks/session-log.sh

@@ -548,13 +548,86 @@ handle_pre_compact() {
   generate_session_output "$(resolve_transcript)"
 }
 
+# ============================================================
+# Agent registry heartbeat — register this agent with CAWS
+# ============================================================
+AGENTS_REGISTRY="${CWD}/.caws/agents.json"
+
+heartbeat_agent() {
+  [ "$SESSION_ID" = "unknown" ] && return
+  [ ! -d "${CWD}/.caws" ] && return
+
+  local model_val
+  model_val=$(echo "$INPUT" | jq -r '.model // "unknown"' 2>/dev/null)
+
+  local registry
+  if [ -f "$AGENTS_REGISTRY" ]; then
+    registry=$(cat "$AGENTS_REGISTRY" 2>/dev/null || echo '{"version":1,"agents":{}}')
+  else
+    registry='{"version":1,"agents":{}}'
+  fi
+
+  registry=$(echo "$registry" | python3 -c "
+import json, sys
+from datetime import datetime, timedelta, timezone
+
+TTL = timedelta(minutes=30)
+now = datetime.now(timezone.utc)
+sid = '$SESSION_ID'
+model = '$model_val'
+
+data = json.load(sys.stdin)
+agents = data.get('agents', {})
+
+pruned = {}
+for k, entry in agents.items():
+    try:
+        last = datetime.fromisoformat(entry['lastSeen'].replace('Z', '+00:00'))
+        if now - last < TTL:
+            pruned[k] = entry
+    except (KeyError, ValueError):
+        pass
+
+existing = pruned.get(sid, {})
+pruned[sid] = {
+    'sessionId': sid,
+    'platform': 'claude-code',
+    'model': model if model != 'unknown' else existing.get('model'),
+    'specId': existing.get('specId'),
+    'ttl': 1800000,
+    'firstSeen': existing.get('firstSeen', now.strftime('%Y-%m-%dT%H:%M:%SZ')),
+    'lastSeen': now.strftime('%Y-%m-%dT%H:%M:%SZ'),
+}
+
+data['agents'] = pruned
+json.dump(data, sys.stdout, indent=2)
+" 2>/dev/null)
+
+  [ -n "$registry" ] && echo "$registry" > "$AGENTS_REGISTRY"
+}
+
+remove_agent() {
+  [ "$SESSION_ID" = "unknown" ] && return
+  [ ! -f "$AGENTS_REGISTRY" ] && return
+
+  python3 -c "
+import json
+sid = '$SESSION_ID'
+with open('$AGENTS_REGISTRY', 'r') as f:
+    data = json.load(f)
+data.get('agents', {}).pop(sid, None)
+with open('$AGENTS_REGISTRY', 'w') as f:
+    json.dump(data, f, indent=2)
+" 2>/dev/null || true
+}
+
 # ============================================================
 # DISPATCH
 # ============================================================
 case "$HOOK_EVENT" in
-  SessionStart)   handle_session_start ;;
-  Stop)           handle_stop ;;
-  PreCompact)     handle_pre_compact ;;
+  SessionStart)   handle_session_start; heartbeat_agent ;;
+  Stop)           handle_stop; remove_agent ;;
+  PreCompact)     handle_pre_compact; heartbeat_agent ;;
   *)              ;; # Other events: no-op
 esac
 

package/dist/templates/.claude/hooks/stop-worktree-check.sh

@@ -25,7 +25,7 @@ if [[ -f "$PROJECT_DIR/.caws/worktrees.json" ]] && command -v node >/dev/null 2>
   ACTIVE_INFO=$(node -e "
     try {
       var reg = JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.caws/worktrees.json', 'utf8'));
-      var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active'; });
+      var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active' || w.status === 'fresh' || w.status === 'merged'; });
       if (active.length > 0) {
         console.log(active.length + ':' + active.map(function(w) { return w.name; }).join(', '));
       } else {