@ekkos/cli 0.2.0

package/templates/hooks/hooks.json

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "bash .claude/hooks/session-start.sh"
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "type": "command",
+        "command": "bash .claude/hooks/user-prompt-submit.sh"
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": "bash .claude/hooks/stop.sh"
+      }
+    ],
+    "AssistantResponse": [
+      {
+        "type": "command",
+        "command": "bash .claude/hooks/assistant-response.sh"
+      }
+    ]
+  }
+}

package/templates/hooks/lib/contract.sh

@@ -0,0 +1,320 @@
+#!/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"
+  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/hooks/lib/state.sh

@@ -0,0 +1,158 @@
+#!/bin/bash
+# ═══════════════════════════════════════════════════════════════════════════
+# ekkOS™ Hook State Management Library (Portable)
+# Shared state functions for coordinating between hooks
+# ═══════════════════════════════════════════════════════════════════════════
+
+# Get project root (where .claude directory lives)
+get_project_root() {
+  local script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  echo "$(dirname "$(dirname "$script_dir")")"
+}
+
+PROJECT_ROOT=$(get_project_root)
+STATE_DIR="$PROJECT_ROOT/.claude/state"
+
+# Ensure state directory exists
+mkdir -p "$STATE_DIR"
+
+# ═══════════════════════════════════════════════════════════════════════════
+# State File Management
+# ═══════════════════════════════════════════════════════════════════════════
+
+# Save patterns for session
+save_patterns() {
+  local session_id="$1"
+  local patterns="$2"
+  local model_used="$3"
+
+  local state_file="$STATE_DIR/patterns-${session_id}.json"
+
+  jq -n \
+    --argjson patterns "$patterns" \
+    --arg model "$model_used" \
+    --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    '{
+      patterns: $patterns,
+      model_used: $model,
+      saved_at: $timestamp
+    }' > "$state_file"
+}
+
+# Load patterns for session
+load_patterns() {
+  local session_id="$1"
+  local state_file="$STATE_DIR/patterns-${session_id}.json"
+
+  if [ -f "$state_file" ]; then
+    cat "$state_file"
+  else
+    echo '{}'
+  fi
+}
+
+# Clear patterns for session (after capture)
+clear_patterns() {
+  local session_id="$1"
+  rm -f "$STATE_DIR/patterns-${session_id}.json"
+}
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Capture Deduplication
+# ═══════════════════════════════════════════════════════════════════════════
+
+# Generate hash for conversation turn
+generate_turn_hash() {
+  local user_query="$1"
+  local assistant_response="$2"
+
+  echo "${user_query}${assistant_response}" | md5sum | cut -d' ' -f1 2>/dev/null || \
+    echo "${user_query}${assistant_response}" | md5 2>/dev/null
+}
+
+# Check if turn was already captured
+was_turn_captured() {
+  local session_id="$1"
+  local turn_hash="$2"
+
+  local capture_log="$STATE_DIR/captures-${session_id}.log"
+
+  if [ -f "$capture_log" ]; then
+    grep -q "^${turn_hash}$" "$capture_log"
+    return $?
+  fi
+
+  return 1 # Not captured
+}
+
+# Mark turn as captured
+mark_turn_captured() {
+  local session_id="$1"
+  local turn_hash="$2"
+
+  local capture_log="$STATE_DIR/captures-${session_id}.log"
+
+  echo "$turn_hash" >> "$capture_log"
+
+  # Keep only last 100 hashes
+  if [ $(wc -l < "$capture_log" 2>/dev/null || echo 0) -gt 100 ]; then
+    tail -100 "$capture_log" > "${capture_log}.tmp"
+    mv "${capture_log}.tmp" "$capture_log"
+  fi
+}
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Hook Coordination
+# ═══════════════════════════════════════════════════════════════════════════
+
+# Lock for preventing race conditions
+acquire_lock() {
+  local session_id="$1"
+  local lock_file="$STATE_DIR/lock-${session_id}.lock"
+  local timeout=5
+  local waited=0
+
+  while [ -f "$lock_file" ] && [ $waited -lt $timeout ]; do
+    sleep 0.1
+    waited=$((waited + 1))
+  done
+
+  if [ -f "$lock_file" ]; then
+    # Stale lock (older than 10 seconds)
+    local lock_age=$(($(date +%s) - $(stat -f %m "$lock_file" 2>/dev/null || stat -c %Y "$lock_file" 2>/dev/null || echo 0)))
+    if [ $lock_age -gt 10 ]; then
+      rm -f "$lock_file"
+    else
+      return 1 # Failed to acquire
+    fi
+  fi
+
+  # Acquire lock
+  echo $$ > "$lock_file"
+  return 0
+}
+
+# Release lock
+release_lock() {
+  local session_id="$1"
+  local lock_file="$STATE_DIR/lock-${session_id}.lock"
+
+  if [ -f "$lock_file" ] && [ "$(cat "$lock_file")" = "$$" ]; then
+    rm -f "$lock_file"
+  fi
+}
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Cleanup
+# ═══════════════════════════════════════════════════════════════════════════
+
+# Clean up old state files
+cleanup_old_state() {
+  # Remove files older than 24 hours
+  find "$STATE_DIR" -name "*.json" -mtime +1 -delete 2>/dev/null || true
+  find "$STATE_DIR" -name "*.log" -mtime +1 -delete 2>/dev/null || true
+  find "$STATE_DIR" -name "*.lock" -mtime +1 -delete 2>/dev/null || true
+}
+
+# Cleanup on exit
+trap cleanup_old_state EXIT

package/templates/hooks/session-start.ps1

@@ -0,0 +1,41 @@
+# ═══════════════════════════════════════════════════════════════════════════
+# ekkOS_ Hook: SessionStart - Initialize session (Windows)
+# ═══════════════════════════════════════════════════════════════════════════
+
+$ErrorActionPreference = "SilentlyContinue"
+
+# Read input
+$inputJson = [Console]::In.ReadToEnd()
+
+try {
+    $input = $inputJson | ConvertFrom-Json
+    $sessionId = $input.session_id
+} catch {
+    $sessionId = "unknown"
+}
+
+# Initialize state directory
+$stateDir = Join-Path $env:USERPROFILE ".claude\state"
+if (-not (Test-Path $stateDir)) {
+    New-Item -ItemType Directory -Path $stateDir -Force | Out-Null
+}
+
+# Reset turn counter for new session
+$stateFile = Join-Path $stateDir "hook-state.json"
+$state = @{
+    turn = 0
+    session_id = $sessionId
+    started_at = (Get-Date).ToString("o")
+} | ConvertTo-Json
+
+Set-Content -Path $stateFile -Value $state -Force
+
+# Save session ID for other hooks
+$sessionFile = Join-Path $stateDir "current-session.json"
+$sessionData = @{
+    session_id = $sessionId
+} | ConvertTo-Json
+
+Set-Content -Path $sessionFile -Value $sessionData -Force
+
+Write-Output "ekkOS session initialized"