@ekkos/cli 0.2.18 → 1.0.0

package/templates/ekkos-manifest.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://ekkos.dev/schemas/manifest-v1.json",
   "manifestVersion": "1.0.0",
-  "generatedAt": "2026-01-22T06:19:22.744Z",
+  "generatedAt": "2026-02-18T04:29:25.535Z",
   "platforms": {
     "darwin": {
       "configDir": "~/.ekkos",
@@ -68,14 +68,14 @@
           "source": "hooks/user-prompt-submit.sh",
           "destination": "user-prompt-submit.sh",
           "description": "User prompt submit hook (Unix)",
-          "checksum": "0e006eb7becba874f34fc622c9ee83b3c96a6e00daf95db840369894af94abf3",
+          "checksum": "ef294d0088a94c6588a91fc91e6cc06a14dd46bc83ca09d73c64abfb11984f40",
           "executable": true
         },
         {
           "source": "hooks/stop.sh",
           "destination": "stop.sh",
           "description": "Session stop hook (Unix)",
-          "checksum": "fd436ea847bf6fbe367f8aa61ddf6d97e8605837badc3af8d433b59599ef6615",
+          "checksum": "f3b4495c0c2bbdf5bfef762568faec7b70b41b463dad4c88b37cf7ee32b5257d",
           "executable": true
         },
         {
@@ -124,14 +124,14 @@
           "source": "hooks/lib/contract.sh",
           "destination": "lib/contract.sh",
           "description": "Hook contract library",
-          "checksum": "1d86128a2a4a25e653a02c4eb08dbfd28db53063c618cd43b85f0603a135e8b2",
+          "checksum": "3ef16930ba10cd37a1c5fa8469ec13a6a84cadb882d3f9a96c72da875ba07fc7",
           "executable": true
         },
         {
           "source": "hooks/lib/state.sh",
           "destination": "lib/state.sh",
           "description": "Hook state management library",
-          "checksum": "ba72c00a1fb0f6768e37aff754ad6ac0e8e20aa0b9b393193e2d92357cac5a71",
+          "checksum": "99223ce9b869d78762084ff184327fa2814af7a16e5f2ac9619af43b5e551d7c",
           "executable": true
         }
       ]

package/templates/hooks/lib/contract.sh

@@ -78,7 +78,7 @@ write_turn_contract() {
   "retrieved_directive_ids": $directive_array,
   "timestamp": "$timestamp",
   "query_hash": "$query_hash",
-  "ekkos_strict": ${EKKOS_STRICT:-0}
+  "ekkos_strict": ${EKKOS_STRICT:-1}
 }
 EOF
 
@@ -134,7 +134,7 @@ cleanup_turn_contract() {
 
 # Check if strict mode is enabled
 is_strict_mode() {
-  [ "${EKKOS_STRICT:-0}" = "1" ]
+  [ "${EKKOS_STRICT:-1}" = "1" ]  # DEFAULT: ON
 }
 
 # Generate strict mode blocker message for Claude Code
@@ -157,50 +157,57 @@ EOF
 }
 
 # Validate PatternGuard coverage (returns 0-100)
+# PORTABLE: Works on macOS without Perl regex (grep -P)
 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)
+  # Count total patterns - more robust counting
+  local total_count=0
+  if [ -n "$pattern_ids" ]; then
+    total_count=$(echo "$pattern_ids" | tr ',' '\n' | grep -v '^$' | wc -l | tr -d ' ')
+  fi
 
   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
+  # Extract acknowledged IDs using portable awk (works on macOS and Linux)
   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
+  # Use awk to extract SELECT block and count IDs - PORTABLE approach
+  local select_count=0
+  select_count=$(echo "$assistant_response" | awk '
+    /\[ekkOS_SELECT\]/{in_block=1; next}
+    /\[\/ekkOS_SELECT\]/{in_block=0}
+    in_block && /id:/{count++}
+    END{print count+0}
+  ')
+  acknowledged_count=$((acknowledged_count + select_count))
+
+  # Use awk to extract SKIP block and count IDs
+  local skip_count=0
+  skip_count=$(echo "$assistant_response" | awk '
+    /\[ekkOS_SKIP\]/{in_block=1; next}
+    /\[\/ekkOS_SKIP\]/{in_block=0}
+    in_block && /id:/{count++}
+    END{print count+0}
+  ')
+  acknowledged_count=$((acknowledged_count + skip_count))
 
   # 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
+    apply_count=$(echo "$assistant_response" | grep -c '\[ekkOS_APPLY\]' 2>/dev/null || echo 0)
+    acknowledged_count=$((acknowledged_count + apply_count))
   fi
 
   # Calculate coverage percentage
-  local coverage
-  coverage=$((acknowledged_count * 100 / total_count))
+  local coverage=0
+  if [ "$total_count" -gt 0 ]; then
+    coverage=$((acknowledged_count * 100 / total_count))
+  fi
 
   # Cap at 100%
   if [ "$coverage" -gt 100 ]; then
@@ -255,11 +262,16 @@ EOF
 }
 
 # Determine if turn is compliant
+# ROBUST: Handles edge cases with non-numeric or empty values
 is_turn_compliant() {
-  local retrieval_ok="$1"
-  local pattern_guard_coverage="$2"
-  local footer_present="$3"
-  local pattern_count="$4"
+  local retrieval_ok="${1:-true}"
+  local pattern_guard_coverage="${2:-100}"
+  local footer_present="${3:-true}"
+  local pattern_count="${4:-0}"
+
+  # Sanitize numeric values (default to safe values)
+  pattern_guard_coverage=$(echo "$pattern_guard_coverage" | grep -oE '^[0-9]+$' || echo "100")
+  pattern_count=$(echo "$pattern_count" | grep -oE '^[0-9]+$' || echo "0")
 
   # Retrieval must have succeeded
   if [ "$retrieval_ok" != "true" ]; then

package/templates/hooks/lib/count-tokens.cjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * Token counter for Claude Code hooks
+ * Extracts ACTUAL token data from Anthropic API usage field
+ *
+ * The transcript contains the real usage data from each API response:
+ * - input_tokens: new tokens in this request
+ * - cache_read_input_tokens: cached tokens from previous turns
+ * - cache_creation_input_tokens: tokens added to cache
+ *
+ * Usage:
+ *   node count-tokens.cjs <transcript.jsonl>          -> outputs total token count
+ *   node count-tokens.cjs <transcript.jsonl> --json   -> outputs full breakdown as JSON
+ */
+
+const fs = require('fs');
+
+const filePath = process.argv[2];
+const outputJson = process.argv.includes('--json');
+
+if (!filePath) {
+  console.error('Usage: count-tokens.cjs <transcript.jsonl> [--json]');
+  process.exit(1);
+}
+
+if (!fs.existsSync(filePath)) {
+  console.error(`[count-tokens] ERROR: File not found: ${filePath}`);
+  process.exit(1);
+}
+
+/**
+ * Extract token breakdown from the most recent assistant message's usage field
+ * This is the authoritative data from Anthropic's API
+ */
+function getTokenBreakdown(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.trim().split('\n').filter(Boolean);
+
+  // Find the most recent assistant message with usage data
+  let latestUsage = null;
+
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+
+      if (entry.type === 'assistant' && entry.message?.usage) {
+        latestUsage = entry.message.usage;
+      }
+    } catch (e) {
+      continue;
+    }
+  }
+
+  if (!latestUsage) {
+    return {
+      input_tokens: 0,
+      cache_read_tokens: 0,
+      cache_creation_tokens: 0,
+      total_tokens: 0,
+      output_tokens: 0
+    };
+  }
+
+  const inputTokens = latestUsage.input_tokens || 0;
+  const cacheRead = latestUsage.cache_read_input_tokens || 0;
+  const cacheCreation = latestUsage.cache_creation_input_tokens || 0;
+  const outputTokens = latestUsage.output_tokens || 0;
+
+  return {
+    input_tokens: inputTokens,
+    cache_read_tokens: cacheRead,
+    cache_creation_tokens: cacheCreation,
+    total_tokens: inputTokens + cacheRead + cacheCreation,
+    output_tokens: outputTokens
+  };
+}
+
+const breakdown = getTokenBreakdown(filePath);
+
+if (outputJson) {
+  // Output full breakdown as JSON (for API)
+  console.log(JSON.stringify(breakdown));
+} else {
+  // Output just the total (backward compatible)
+  console.log(breakdown.total_tokens);
+}

package/templates/hooks/lib/ekkos-reminders.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+# ═══════════════════════════════════════════════════════════════════════════
+# ekkOS Tool Usage Reminders - Inject proactive tool usage hints
+# ═══════════════════════════════════════════════════════════════════════════
+
+# Detect if user query suggests using specific ekkOS tools
+# Returns markdown reminders to inject into Claude's context
+
+get_ekkos_reminders() {
+  local query="$1"
+  local prev_response="$2"
+  local reminders=""
+
+  # Convert to lowercase for matching
+  query_lower=$(echo "$query" | tr '[:upper:]' '[:lower:]')
+  response_lower=$(echo "$prev_response" | tr '[:upper:]' '[:lower:]')
+
+  # ═══════════════════════════════════════════════════════════════════════════
+  # ekkOS_Search - Before answering technical questions
+  # ═══════════════════════════════════════════════════════════════════════════
+  if echo "$query_lower" | grep -qE "(how do|how to|what is|why|explain|security|authentication|database|rls|deployment|error|bug|fix)"; then
+    reminders+="🧠 **ekkOS_Search Required**: Search memory before answering technical questions\n"
+  fi
+
+  # ═══════════════════════════════════════════════════════════════════════════
+  # ekkOS_Forge - When fixing bugs or learning
+  # ═══════════════════════════════════════════════════════════════════════════
+  if echo "$response_lower" | grep -qE "(fixed|solved|resolved|bug|issue|error|migration|implemented|created|updated)"; then
+    reminders+="🔨 **ekkOS_Forge Recommended**: Forge pattern after fixing bugs or implementing solutions\n"
+  fi
+
+  # ═══════════════════════════════════════════════════════════════════════════
+  # ekkOS_Directive - User preferences
+  # ═══════════════════════════════════════════════════════════════════════════
+  if echo "$query_lower" | grep -qE "(always|never|dont|don't|prefer|avoid|should not|shouldn't)"; then
+    directive_type="PREFER"
+    if echo "$query_lower" | grep -qE "(always|must)"; then
+      directive_type="MUST"
+    elif echo "$query_lower" | grep -qE "(never|dont|don't|avoid|should not)"; then
+      directive_type="NEVER"
+    fi
+    reminders+="📋 **ekkOS_Directive Required**: User stated a preference - save as ${directive_type} directive\n"
+  fi
+
+  # ═══════════════════════════════════════════════════════════════════════════
+  # ekkOS_Conflict - Destructive operations
+  # ═══════════════════════════════════════════════════════════════════════════
+  if echo "$query_lower" | grep -qE "(delete|remove|drop|truncate|destroy|wipe)"; then
+    reminders+="⚠️  **ekkOS_Conflict Required**: Check for conflicts before destructive operations\n"
+  fi
+
+  # ═══════════════════════════════════════════════════════════════════════════
+  # ekkOS_Plan - Complex multi-step tasks
+  # ═══════════════════════════════════════════════════════════════════════════
+  if echo "$query_lower" | grep -qE "(implement|build|create.*feature|add.*functionality|refactor|migrate)"; then
+    reminders+="📝 **ekkOS_Plan Recommended**: Create structured plan for multi-step implementation\n"
+  fi
+
+  # ═══════════════════════════════════════════════════════════════════════════
+  # ekkOS_StoreSecret - Credentials shared
+  # ═══════════════════════════════════════════════════════════════════════════
+  if echo "$query_lower" | grep -qE "(api.?key|token|password|secret|credential|github.*key|openai.*key)"; then
+    reminders+="🔐 **ekkOS_StoreSecret Available**: Use to securely store credentials (AES-256-GCM)\n"
+  fi
+
+  # ═══════════════════════════════════════════════════════════════════════════
+  # ekkOS_Recall - Past conversations
+  # ═══════════════════════════════════════════════════════════════════════════
+  if echo "$query_lower" | grep -qE "(yesterday|last week|previously|we discussed|earlier|before)"; then
+    reminders+="🕐 **ekkOS_Recall Available**: Retrieve past conversations by time\n"
+  fi
+
+  # ═══════════════════════════════════════════════════════════════════════════
+  # ekkOS_Codebase - Project-specific search
+  # ═══════════════════════════════════════════════════════════════════════════
+  if echo "$query_lower" | grep -qE "(in this project|in our codebase|where is.*defined|find.*file)"; then
+    reminders+="📂 **ekkOS_Codebase Available**: Search project-specific memory\n"
+  fi
+
+  # ═══════════════════════════════════════════════════════════════════════════
+  # ekkOS_Export - Backup request
+  # ═══════════════════════════════════════════════════════════════════════════
+  if echo "$query_lower" | grep -qE "(export|backup|download|save.*memory|portable)"; then
+    reminders+="💾 **ekkOS_Export Available**: Export all patterns/directives as portable JSON\n"
+  fi
+
+  # ═══════════════════════════════════════════════════════════════════════════
+  # ekkOS_Summary - Show activity
+  # ═══════════════════════════════════════════════════════════════════════════
+  if echo "$query_lower" | grep -qE "(what did.*do|ekkos.*activity|memory.*stats|show.*patterns)"; then
+    reminders+="📊 **ekkOS_Summary Available**: Show recent ekkOS activity\n"
+  fi
+
+  echo "$reminders"
+}
+
+# Export function
+export -f get_ekkos_reminders

package/templates/hooks/lib/state.sh

@@ -20,25 +20,40 @@ mkdir -p "$STATE_DIR"
 # State File Management
 # ═══════════════════════════════════════════════════════════════════════════
 
-# Save patterns for session
+# Save patterns for session (with retrieval_token for verified tracking)
 save_patterns() {
   local session_id="$1"
   local patterns="$2"
   local model_used="$3"
+  local retrieval_token="${4:-}"  # Optional retrieval_token for verified applications
 
   local state_file="$STATE_DIR/patterns-${session_id}.json"
 
   jq -n \
     --argjson patterns "$patterns" \
     --arg model "$model_used" \
+    --arg token "$retrieval_token" \
     --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
     '{
       patterns: $patterns,
       model_used: $model,
+      retrieval_token: $token,
       saved_at: $timestamp
     }' > "$state_file"
 }
 
+# Get retrieval token from saved patterns
+get_retrieval_token() {
+  local session_id="$1"
+  local state_file="$STATE_DIR/patterns-${session_id}.json"
+
+  if [ -f "$state_file" ]; then
+    jq -r '.retrieval_token // ""' "$state_file" 2>/dev/null
+  else
+    echo ""
+  fi
+}
+
 # Load patterns for session
 load_patterns() {
   local session_id="$1"
@@ -57,6 +72,43 @@ clear_patterns() {
   rm -f "$STATE_DIR/patterns-${session_id}.json"
 }
 
+# ═══════════════════════════════════════════════════════════════════════════
+# Conversation Context (for Golden Loop MEASURE phase)
+# ═══════════════════════════════════════════════════════════════════════════
+
+# Save current conversation context for pattern tracking
+# Called by user-prompt-submit.sh when new query is submitted
+save_conversation_context() {
+  local session_id="$1"
+  local user_query="$2"
+  local prev_response="$3"
+
+  local context_file="$STATE_DIR/conversation-${session_id}.json"
+
+  jq -n \
+    --arg query "$user_query" \
+    --arg response "$prev_response" \
+    --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    '{
+      query: $query,
+      response: $response,
+      saved_at: $timestamp
+    }' > "$context_file" 2>/dev/null || true
+}
+
+# Load current conversation context
+# Called by post-tool-use.sh when tracking pattern applications
+load_conversation_context() {
+  local session_id="$1"
+  local context_file="$STATE_DIR/conversation-${session_id}.json"
+
+  if [ -f "$context_file" ]; then
+    cat "$context_file"
+  else
+    echo '{"query":"","response":""}'
+  fi
+}
+
 # ═══════════════════════════════════════════════════════════════════════════
 # Capture Deduplication
 # ═══════════════════════════════════════════════════════════════════════════