@ekkos/cli 1.2.17 → 1.3.0

package/templates/windsurf-hooks/lib/contract.sh

@@ -1,322 +0,0 @@
-#!/bin/bash
-# ═══════════════════════════════════════════════════════════════════════════
-# ekkOS_ Turn Contract Library
-#
-# Shared functions for Golden Loop compliance enforcement.
-# Used by BOTH Claude Code (.claude/) and Cursor (.cursor/) hooks.
-#
-# TURN CONTRACT: Evidence that retrieval occurred before answering.
-# This is the SINGLE SOURCE OF TRUTH for compliance auditing.
-# ═══════════════════════════════════════════════════════════════════════════
-
-# Get contract directory based on environment
-get_contract_dir() {
-  local source="${1:-claude-code}"
-  local project_root="${2:-$PROJECT_ROOT}"
-
-  if [ "$source" = "cursor" ]; then
-    echo "$project_root/.cursor/state/ekkos"
-  elif [ "$source" = "windsurf" ]; then
-    echo "$project_root/.windsurf/state/ekkos"
-  else
-    echo "$project_root/.claude/state/ekkos"
-  fi
-}
-
-# Generate stable hash of user prompt (for deduplication)
-generate_query_hash() {
-  local query="$1"
-  # Use md5 on macOS, md5sum on Linux
-  if command -v md5 >/dev/null 2>&1; then
-    echo -n "$query" | md5 | cut -c1-16
-  elif command -v md5sum >/dev/null 2>&1; then
-    echo -n "$query" | md5sum | cut -c1-16
-  else
-    # Fallback: simple hash using cksum
-    echo -n "$query" | cksum | cut -d' ' -f1
-  fi
-}
-
-# Write turn contract at RETRIEVAL time
-# This is the EVIDENCE that retrieval happened before answering
-write_turn_contract() {
-  local session_id="$1"
-  local retrieval_ok="$2"
-  local retrieval_source="$3"
-  local pattern_ids="$4"      # Comma-separated list
-  local directive_ids="$5"    # Comma-separated list
-  local query_hash="$6"
-  local project_root="${7:-$PROJECT_ROOT}"
-
-  local contract_dir
-  contract_dir=$(get_contract_dir "$retrieval_source" "$project_root")
-  mkdir -p "$contract_dir" 2>/dev/null || return 1
-
-  local contract_file="$contract_dir/turn-contract-${session_id}.json"
-  local timestamp
-  timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-
-  # Convert comma-separated IDs to JSON array
-  local pattern_array
-  local directive_array
-  if [ -n "$pattern_ids" ]; then
-    pattern_array=$(echo "$pattern_ids" | tr ',' '\n' | grep -v '^$' | jq -R . | jq -s .)
-  else
-    pattern_array="[]"
-  fi
-  if [ -n "$directive_ids" ]; then
-    directive_array=$(echo "$directive_ids" | tr ',' '\n' | grep -v '^$' | jq -R . | jq -s .)
-  else
-    directive_array="[]"
-  fi
-
-  # Write contract
-  cat > "$contract_file" << EOF
-{
-  "session_id": "$session_id",
-  "retrieval_ok": $retrieval_ok,
-  "retrieval_source": "$retrieval_source",
-  "retrieved_pattern_ids": $pattern_array,
-  "retrieved_directive_ids": $directive_array,
-  "timestamp": "$timestamp",
-  "query_hash": "$query_hash",
-  "ekkos_strict": ${EKKOS_STRICT:-0}
-}
-EOF
-
-  return 0
-}
-
-# Read turn contract
-read_turn_contract() {
-  local session_id="$1"
-  local retrieval_source="$2"
-  local project_root="${3:-$PROJECT_ROOT}"
-
-  local contract_dir
-  contract_dir=$(get_contract_dir "$retrieval_source" "$project_root")
-  local contract_file="$contract_dir/turn-contract-${session_id}.json"
-
-  if [ -f "$contract_file" ]; then
-    cat "$contract_file"
-    return 0
-  else
-    return 1
-  fi
-}
-
-# Extract field from contract JSON
-get_contract_field() {
-  local contract_json="$1"
-  local field="$2"
-
-  echo "$contract_json" | jq -r ".$field // \"\"" 2>/dev/null
-}
-
-# Get array field as comma-separated string
-get_contract_array() {
-  local contract_json="$1"
-  local field="$2"
-
-  echo "$contract_json" | jq -r ".$field // [] | join(\",\")" 2>/dev/null
-}
-
-# Cleanup turn contract (only after successful capture)
-cleanup_turn_contract() {
-  local session_id="$1"
-  local retrieval_source="$2"
-  local project_root="${3:-$PROJECT_ROOT}"
-
-  local contract_dir
-  contract_dir=$(get_contract_dir "$retrieval_source" "$project_root")
-  local contract_file="$contract_dir/turn-contract-${session_id}.json"
-
-  rm -f "$contract_file" 2>/dev/null
-}
-
-# Check if strict mode is enabled
-is_strict_mode() {
-  [ "${EKKOS_STRICT:-0}" = "1" ]
-}
-
-# Generate strict mode blocker message for Claude Code
-get_strict_blocker_message() {
-  cat << 'EOF'
-════════════════════════════════════════════════════════════════════════════
-⛔ EKKOS_STRICT MODE: RETRIEVAL FAILED — DO NOT ANSWER
-
-ekkOS memory retrieval failed or was not authenticated.
-In STRICT mode, you MUST NOT answer technical questions without memory context.
-
-ACTION REQUIRED:
-1. Check if ekkOS is connected: Run `ekkOS: Connect` in VS Code
-2. Verify auth token exists: ~/.ekkos/config.json
-3. Retry the request after connecting
-
-DO NOT proceed with answering. The Golden Loop requires retrieval FIRST.
-════════════════════════════════════════════════════════════════════════════
-EOF
-}
-
-# Validate PatternGuard coverage (returns 0-100)
-calculate_pattern_guard_coverage() {
-  local assistant_response="$1"
-  local pattern_ids="$2"  # Comma-separated
-
-  # Count total patterns
-  local total_count
-  total_count=$(echo "$pattern_ids" | tr ',' '\n' | grep -c '.' || echo 0)
-
-  if [ "$total_count" -eq 0 ]; then
-    echo "100"  # No patterns = 100% coverage by definition
-    return 0
-  fi
-
-  # Extract acknowledged IDs from [ekkOS_SELECT] and [ekkOS_SKIP] blocks
-  local acknowledged_count=0
-
-  # Check SELECT block
-  local select_block
-  select_block=$(echo "$assistant_response" | grep -ozP '\[ekkOS_SELECT\][\s\S]*?\[/ekkOS_SELECT\]' 2>/dev/null | tr '\0' '\n' || true)
-  if [ -n "$select_block" ]; then
-    local select_count
-    select_count=$(echo "$select_block" | grep -oE 'id:\s*[a-f0-9-]+' | wc -l | tr -d ' ')
-    acknowledged_count=$((acknowledged_count + select_count))
-  fi
-
-  # Check SKIP block
-  local skip_block
-  skip_block=$(echo "$assistant_response" | grep -ozP '\[ekkOS_SKIP\][\s\S]*?\[/ekkOS_SKIP\]' 2>/dev/null | tr '\0' '\n' || true)
-  if [ -n "$skip_block" ]; then
-    local skip_count
-    skip_count=$(echo "$skip_block" | grep -oE 'id:\s*[a-f0-9-]+' | wc -l | tr -d ' ')
-    acknowledged_count=$((acknowledged_count + skip_count))
-  fi
-
-  # Legacy: Check for [ekkOS_APPLY] markers (fallback)
-  if [ "$acknowledged_count" -eq 0 ]; then
-    local apply_count
-    apply_count=$(echo "$assistant_response" | grep -c '\[ekkOS_APPLY\]' || echo 0)
-    acknowledged_count=$apply_count
-  fi
-
-  # Calculate coverage percentage
-  local coverage
-  coverage=$((acknowledged_count * 100 / total_count))
-
-  # Cap at 100%
-  if [ "$coverage" -gt 100 ]; then
-    coverage=100
-  fi
-
-  echo "$coverage"
-}
-
-# Check for ekkOS footer presence
-check_footer_present() {
-  local assistant_response="$1"
-
-  # Look for the mandatory footer format:
-  # 🧠 **ekkOS_™** · 📅 YYYY-MM-DD
-  # OR
-  # {IDE} ({Model}) · 🧠 **ekkOS_™** · 📅 {Timestamp}
-
-  if echo "$assistant_response" | grep -qE '🧠.*ekkOS.*📅.*[0-9]{4}-[0-9]{2}-[0-9]{2}'; then
-    echo "true"
-    return 0
-  else
-    echo "false"
-    return 1
-  fi
-}
-
-# Build compliance metadata for capture
-build_compliance_metadata() {
-  local retrieval_ok="$1"
-  local pattern_guard_coverage="$2"
-  local footer_present="$3"
-  local ekkos_strict="$4"
-  local retrieved_count="$5"
-
-  local pattern_guard_required="false"
-  if [ "$retrieved_count" -gt 0 ]; then
-    pattern_guard_required="true"
-  fi
-
-  cat << EOF
-{
-  "retrieval_ok": $retrieval_ok,
-  "pattern_guard_required": $pattern_guard_required,
-  "pattern_guard_coverage_pct": $pattern_guard_coverage,
-  "footer_present": $footer_present,
-  "ekkos_strict": $ekkos_strict,
-  "retrieved_count": $retrieved_count,
-  "compliance_version": "1.0"
-}
-EOF
-}
-
-# Determine if turn is compliant
-is_turn_compliant() {
-  local retrieval_ok="$1"
-  local pattern_guard_coverage="$2"
-  local footer_present="$3"
-  local pattern_count="$4"
-
-  # Retrieval must have succeeded
-  if [ "$retrieval_ok" != "true" ]; then
-    echo "false"
-    return 1
-  fi
-
-  # If patterns were retrieved, PatternGuard must be 100%
-  if [ "$pattern_count" -gt 0 ] && [ "$pattern_guard_coverage" -lt 100 ]; then
-    echo "false"
-    return 1
-  fi
-
-  # Footer must be present
-  if [ "$footer_present" != "true" ]; then
-    echo "false"
-    return 1
-  fi
-
-  echo "true"
-  return 0
-}
-
-# Generate violation reason
-get_violation_reason() {
-  local retrieval_ok="$1"
-  local pattern_guard_coverage="$2"
-  local footer_present="$3"
-  local pattern_count="$4"
-
-  local reasons=""
-
-  if [ "$retrieval_ok" != "true" ]; then
-    reasons="retrieval_failed"
-  fi
-
-  if [ "$pattern_count" -gt 0 ] && [ "$pattern_guard_coverage" -lt 100 ]; then
-    if [ -n "$reasons" ]; then
-      reasons="$reasons,pattern_guard_incomplete"
-    else
-      reasons="pattern_guard_incomplete"
-    fi
-  fi
-
-  if [ "$footer_present" != "true" ]; then
-    if [ -n "$reasons" ]; then
-      reasons="$reasons,footer_missing"
-    else
-      reasons="footer_missing"
-    fi
-  fi
-
-  if [ -z "$reasons" ]; then
-    reasons="none"
-  fi
-
-  echo "$reasons"
-}

package/templates/windsurf-hooks/post-cascade-response.sh

@@ -1,251 +0,0 @@
-#!/bin/bash
-# ═══════════════════════════════════════════════════════════════════════════
-# ekkOS_ Hook: post_cascade_response (Windsurf Cascade) - CAPTURE + VALIDATE
-#
-# ARCHITECTURE: Dumb Hook, Smart Backend
-# ═══════════════════════════════════════════════════════════════════════════
-# This hook runs AFTER Cascade completes a response.
-# It is THE CANONICAL capture path for Windsurf Cascade.
-#
-# FEATURES:
-# - Turn capture to L2 episodic memory
-# - PatternGuard validation (footer + pattern acknowledgment)
-# - Outcome tracking for Golden Loop
-# - Compliance metadata generation
-#
-# Windsurf Hook Input:
-# {
-#   "agent_action_name": "post_cascade_response",
-#   "trajectory_id": "...",
-#   "execution_id": "...",
-#   "timestamp": "...",
-#   "tool_info": {"response": "..."}
-# }
-#
-# Golden Loop Flow:
-# 1. pre_user_prompt: Retrieves patterns + writes turn contract
-# 2. post_cascade_response: Validates response + captures turn + tracks outcomes
-# ═══════════════════════════════════════════════════════════════════════════
-
-set +e  # Don't exit on errors - be bulletproof
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="$(dirname "$(dirname "$SCRIPT_DIR")")"
-STATE_DIR="$PROJECT_ROOT/.windsurf/state"
-mkdir -p "$STATE_DIR" 2>/dev/null || true
-
-# Load turn contract library
-if [ -f "$SCRIPT_DIR/lib/contract.sh" ]; then
-  source "$SCRIPT_DIR/lib/contract.sh" 2>/dev/null || true
-fi
-
-# Fallback functions if library didn't load
-if ! command -v read_turn_contract >/dev/null 2>&1; then
-  read_turn_contract() { return 1; }
-fi
-if ! command -v calculate_pattern_guard_coverage >/dev/null 2>&1; then
-  calculate_pattern_guard_coverage() { echo "100"; }
-fi
-if ! command -v check_footer_present >/dev/null 2>&1; then
-  check_footer_present() { echo "true"; }
-fi
-if ! command -v is_turn_compliant >/dev/null 2>&1; then
-  is_turn_compliant() { echo "true"; }
-fi
-if ! command -v get_violation_reason >/dev/null 2>&1; then
-  get_violation_reason() { echo "none"; }
-fi
-if ! command -v cleanup_turn_contract >/dev/null 2>&1; then
-  cleanup_turn_contract() { return 0; }
-fi
-
-# ═══════════════════════════════════════════════════════════════════════════
-# Read JSON input from stdin (Windsurf format)
-# ═══════════════════════════════════════════════════════════════════════════
-INPUT=$(cat)
-
-# Extract response text from Windsurf format
-RESPONSE_TEXT=$(echo "$INPUT" | jq -r '.tool_info.response // ""' 2>/dev/null || echo "")
-
-# Extract trajectory/session info
-TRAJECTORY_ID=$(echo "$INPUT" | jq -r '.trajectory_id // ""' 2>/dev/null || echo "")
-EXECUTION_ID=$(echo "$INPUT" | jq -r '.execution_id // ""' 2>/dev/null || echo "")
-
-# Generate session ID if not provided
-if [ -z "$TRAJECTORY_ID" ] || [ "$TRAJECTORY_ID" = "null" ]; then
-  TRAJECTORY_ID="windsurf-$(date +%s)-$$"
-fi
-
-SESSION_ID="$TRAJECTORY_ID"
-
-# Skip if empty response
-if [ -z "$RESPONSE_TEXT" ] || [ "$RESPONSE_TEXT" = "null" ]; then
-  exit 0
-fi
-
-# ═══════════════════════════════════════════════════════════════════════════
-# Load auth
-# ═══════════════════════════════════════════════════════════════════════════
-EKKOS_CONFIG="$HOME/.ekkos/config.json"
-AUTH_TOKEN=""
-USER_ID=""
-
-if [ -f "$EKKOS_CONFIG" ]; then
-  AUTH_TOKEN=$(jq -r '.hookApiKey // .apiKey // ""' "$EKKOS_CONFIG" 2>/dev/null || echo "")
-  USER_ID=$(jq -r '.userId // ""' "$EKKOS_CONFIG" 2>/dev/null || echo "")
-fi
-
-if [ -z "$AUTH_TOKEN" ] && [ -f "$PROJECT_ROOT/.env.local" ]; then
-  AUTH_TOKEN=$(grep -E "^SUPABASE_SECRET_KEY=" "$PROJECT_ROOT/.env.local" | cut -d'=' -f2- | tr -d '"' | tr -d "'" | tr -d '\r')
-fi
-
-[ -z "$AUTH_TOKEN" ] && exit 0
-
-MEMORY_API_URL="https://mcp.ekkos.dev"
-
-# ═══════════════════════════════════════════════════════════════════════════
-# Load session state from pre_user_prompt hook
-# ═══════════════════════════════════════════════════════════════════════════
-LAST_QUERY=""
-RETRIEVED_PATTERN_IDS=""
-CONTRACT_DATA=""
-
-# Load the query that triggered this response
-if [ -f "$STATE_DIR/last_query.txt" ]; then
-  LAST_QUERY=$(cat "$STATE_DIR/last_query.txt" 2>/dev/null || echo "")
-fi
-
-# Read the turn contract written by pre_user_prompt
-CONTRACT_DATA=$(read_turn_contract "$SESSION_ID" "windsurf" "$PROJECT_ROOT" 2>/dev/null || echo "")
-
-if [ -n "$CONTRACT_DATA" ]; then
-  RETRIEVAL_OK=$(echo "$CONTRACT_DATA" | jq -r '.retrieval_ok // "false"' 2>/dev/null || echo "false")
-  RETRIEVED_PATTERN_IDS=$(echo "$CONTRACT_DATA" | jq -r '.retrieved_pattern_ids | join(",") // ""' 2>/dev/null || echo "")
-  RETRIEVED_DIRECTIVE_IDS=$(echo "$CONTRACT_DATA" | jq -r '.retrieved_directive_ids | join(",") // ""' 2>/dev/null || echo "")
-  EKKOS_STRICT=$(echo "$CONTRACT_DATA" | jq -r '.ekkos_strict // 0' 2>/dev/null || echo "0")
-else
-  RETRIEVAL_OK="false"
-  EKKOS_STRICT=0
-fi
-
-# Load patterns that were injected
-PATTERN_COUNT=0
-if [ -f "$STATE_DIR/patterns-${SESSION_ID}.json" ]; then
-  PATTERN_COUNT=$(jq 'length' "$STATE_DIR/patterns-${SESSION_ID}.json" 2>/dev/null || echo "0")
-fi
-
-# ═══════════════════════════════════════════════════════════════════════════
-# [PATTERNGUARD] Validate response compliance
-# ═══════════════════════════════════════════════════════════════════════════
-PATTERN_GUARD_COVERAGE=$(calculate_pattern_guard_coverage "$RESPONSE_TEXT" "$RETRIEVED_PATTERN_IDS")
-FOOTER_PRESENT=$(check_footer_present "$RESPONSE_TEXT")
-IS_COMPLIANT=$(is_turn_compliant "$RETRIEVAL_OK" "$PATTERN_GUARD_COVERAGE" "$FOOTER_PRESENT" "$PATTERN_COUNT")
-VIOLATION_REASON=$(get_violation_reason "$RETRIEVAL_OK" "$PATTERN_GUARD_COVERAGE" "$FOOTER_PRESENT" "$PATTERN_COUNT")
-
-# ═══════════════════════════════════════════════════════════════════════════
-# Get turn number
-# ═══════════════════════════════════════════════════════════════════════════
-TURN_FILE="$STATE_DIR/turn_${SESSION_ID}.txt"
-TURN_NUMBER=1
-if [ -f "$TURN_FILE" ]; then
-  TURN_NUMBER=$(cat "$TURN_FILE" 2>/dev/null || echo "0")
-  TURN_NUMBER=$((TURN_NUMBER + 1))
-fi
-echo "$TURN_NUMBER" > "$TURN_FILE"
-
-# ═══════════════════════════════════════════════════════════════════════════
-# [ekkOS_CAPTURE] Capture turn to L2 episodic memory
-# ═══════════════════════════════════════════════════════════════════════════
-# Only capture if we have a query to pair with
-if [ -n "$LAST_QUERY" ]; then
-  # Truncate for API limits
-  QUERY_TRUNCATED="${LAST_QUERY:0:10000}"
-  RESPONSE_TRUNCATED="${RESPONSE_TEXT:0:50000}"
-
-  # Build compliance metadata
-  COMPLIANCE_META=$(cat << EOF
-{
-  "retrieval_ok": $RETRIEVAL_OK,
-  "pattern_guard_required": $(if [ "$PATTERN_COUNT" -gt 0 ]; then echo "true"; else echo "false"; fi),
-  "pattern_guard_coverage_pct": $PATTERN_GUARD_COVERAGE,
-  "footer_present": $FOOTER_PRESENT,
-  "ekkos_strict": $EKKOS_STRICT,
-  "retrieved_count": $PATTERN_COUNT,
-  "compliance_version": "1.0",
-  "is_compliant": $IS_COMPLIANT,
-  "violation_reason": "$VIOLATION_REASON"
-}
-EOF
-)
-
-  CAPTURE_PAYLOAD=$(jq -n \
-    --arg session_id "windsurf-$SESSION_ID" \
-    --arg user_id "${USER_ID:-system}" \
-    --arg user_query "$QUERY_TRUNCATED" \
-    --arg assistant_response "$RESPONSE_TRUNCATED" \
-    --argjson turn_number "$TURN_NUMBER" \
-    --argjson compliance "$COMPLIANCE_META" \
-    '{
-      session_id: $session_id,
-      user_id: $user_id,
-      user_query: $user_query,
-      assistant_response: $assistant_response,
-      metadata: {
-        source: "windsurf-cascade",
-        turn_number: $turn_number,
-        compliance: $compliance
-      }
-    }' 2>/dev/null || echo '{}')
-
-  # Fire and forget - don't block Cascade
-  curl -s -X POST "$MEMORY_API_URL/api/v1/capture" \
-    -H "Authorization: Bearer $AUTH_TOKEN" \
-    -H "Content-Type: application/json" \
-    -d "$CAPTURE_PAYLOAD" \
-    --connect-timeout 2 \
-    --max-time 3 >/dev/null 2>&1 &
-
-  # Track pattern outcomes if acknowledgment found
-  if [ "$PATTERN_COUNT" -gt 0 ]; then
-    # Check for [ekkOS_SELECT] markers and track outcomes
-    SELECT_BLOCK=$(echo "$RESPONSE_TEXT" | grep -ozP '\[ekkOS_SELECT\][\s\S]*?\[/ekkOS_SELECT\]' 2>/dev/null | tr '\0' '\n' || true)
-    if [ -n "$SELECT_BLOCK" ]; then
-      # Extract pattern IDs and track them
-      echo "$SELECT_BLOCK" | grep -oE 'id:\s*[a-f0-9-]+' | sed 's/id:\s*//' | while read -r pattern_id; do
-        # Track successful application
-        curl -s -X POST "$MEMORY_API_URL/api/v1/patterns/outcome" \
-          -H "Authorization: Bearer $AUTH_TOKEN" \
-          -H "Content-Type: application/json" \
-          -d "{\"pattern_id\": \"$pattern_id\", \"success\": true, \"source\": \"windsurf-cascade\"}" \
-          --connect-timeout 1 \
-          --max-time 2 >/dev/null 2>&1 &
-      done
-    fi
-  fi
-
-  # Clear last query so we don't double-capture
-  rm -f "$STATE_DIR/last_query.txt" 2>/dev/null || true
-fi
-
-# ═══════════════════════════════════════════════════════════════════════════
-# Cleanup turn contract after successful capture
-# ═══════════════════════════════════════════════════════════════════════════
-cleanup_turn_contract "$SESSION_ID" "windsurf" "$PROJECT_ROOT" 2>/dev/null || true
-
-# Clean up pattern file
-rm -f "$STATE_DIR/patterns-${SESSION_ID}.json" 2>/dev/null || true
-
-# ═══════════════════════════════════════════════════════════════════════════
-# [NON-COMPLIANCE WARNINGS] If Golden Loop violations detected
-# ═══════════════════════════════════════════════════════════════════════════
-if [ "$IS_COMPLIANT" != "true" ] && [ "${EKKOS_STRICT:-0}" != "1" ]; then
-  # Log violation for analysis (fire and forget)
-  curl -s -X POST "$MEMORY_API_URL/api/v1/capture/violation" \
-    -H "Authorization: Bearer $AUTH_TOKEN" \
-    -H "Content-Type: application/json" \
-    -d "{\"session_id\": \"windsurf-$SESSION_ID\", \"user_id\": \"${USER_ID:-system}\", \"violation_reason\": \"$VIOLATION_REASON\", \"turn_number\": $TURN_NUMBER}" \
-    --connect-timeout 1 \
-    --max-time 2 >/dev/null 2>&1 &
-fi
-
-exit 0