claude-flow-novice 2.18.5 → 2.18.7

package/.claude/skills/cfn-knowledge-base/lib/workflow/track-edge-case.sh

@@ -0,0 +1,290 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# track-edge-case.sh - Capture and analyze skill execution failures
+# Records edge cases, detects patterns, and triggers skill update proposals
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source parameterized query library for SQL injection prevention
+source "${SCRIPT_DIR}/../bootstrap/sqlite-params.sh"
+
+DB_PATH="${DB_PATH:-${SCRIPT_DIR}/../../../../data/workflow-codification.db}"
+RECURRENCE_THRESHOLD=3
+
+# Initialize database schema
+init_database() {
+    sqlite3 "$DB_PATH" <<'EOF'
+CREATE TABLE IF NOT EXISTS edge_cases (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    skill_name TEXT NOT NULL,
+    skill_version TEXT NOT NULL,
+    exit_code INTEGER NOT NULL,
+    input_params TEXT NOT NULL,
+    expected_output TEXT,
+    actual_output TEXT,
+    error_message TEXT,
+    timestamp TEXT DEFAULT (datetime('now')),
+    occurrence_count INTEGER DEFAULT 1,
+    edge_case_hash TEXT NOT NULL UNIQUE,
+    status TEXT DEFAULT 'new' CHECK(status IN ('new', 'analyzing', 'proposal_generated', 'resolved')),
+    metadata TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_edge_cases_skill ON edge_cases(skill_name, skill_version);
+CREATE INDEX IF NOT EXISTS idx_edge_cases_status ON edge_cases(status);
+CREATE INDEX IF NOT EXISTS idx_edge_cases_hash ON edge_cases(edge_case_hash);
+CREATE INDEX IF NOT EXISTS idx_edge_cases_timestamp ON edge_cases(timestamp);
+EOF
+}
+
+# Generate unique hash for edge case pattern
+generate_edge_case_hash() {
+    local skill_name="$1"
+    local exit_code="$2"
+    local input_params="$3"
+
+    echo -n "${skill_name}:${exit_code}:${input_params}" | sha256sum | awk '{print $1}'
+}
+
+# Record edge case
+record_edge_case() {
+    local skill_name="$1"
+    local skill_version="$2"
+    local exit_code="$3"
+    local input_params="$4"
+    local expected_output="${5:-}"
+    local actual_output="${6:-}"
+    local error_message="${7:-}"
+    local metadata="${8:-{}}"
+
+    local edge_case_hash
+    edge_case_hash=$(generate_edge_case_hash "$skill_name" "$exit_code" "$input_params")
+
+    # Check if edge case already exists (parameterized query)
+    local existing_count
+    existing_count=$(sqlite_select "$DB_PATH" "SELECT occurrence_count FROM edge_cases WHERE edge_case_hash = ?1" "$edge_case_hash" 2>/dev/null || echo "0")
+
+    if [[ -n "$existing_count" && "$existing_count" != "0" ]]; then
+        # Update existing edge case (parameterized query)
+        local new_count=$((existing_count + 1))
+        sqlite_update "$DB_PATH" \
+            "UPDATE edge_cases SET occurrence_count = ?1, timestamp = datetime('now'), actual_output = ?2, error_message = ?3 WHERE edge_case_hash = ?4" \
+            "$new_count" "$actual_output" "$error_message" "$edge_case_hash"
+        echo "Updated edge case (occurrence: $new_count): $edge_case_hash"
+
+        # Check if threshold reached
+        if [[ $new_count -ge $RECURRENCE_THRESHOLD ]]; then
+            echo "⚠️  Recurrence threshold reached ($new_count >= $RECURRENCE_THRESHOLD)"
+            echo "Generating skill update proposal..."
+
+            # Trigger skill update proposal generation
+            "${SCRIPT_DIR}/generate-skill-update.sh" \
+                --skill-name "$skill_name" \
+                --edge-case-hash "$edge_case_hash" \
+                --occurrence-count "$new_count"
+        fi
+    else
+        # Insert new edge case (parameterized query)
+        sqlite_insert "$DB_PATH" \
+            "INSERT INTO edge_cases (skill_name, skill_version, exit_code, input_params, expected_output, actual_output, error_message, edge_case_hash, metadata) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)" \
+            "$skill_name" "$skill_version" "$exit_code" "$input_params" "$expected_output" "$actual_output" "$error_message" "$edge_case_hash" "$metadata"
+        echo "Recorded new edge case: $edge_case_hash"
+    fi
+}
+
+# Query recurring edge cases
+query_recurring_edge_cases() {
+    local skill_name="${1:-}"
+
+    # Use parameterized query for filtering by skill_name
+    if [[ -n "$skill_name" ]]; then
+        sqlite_select "$DB_PATH" \
+            "SELECT skill_name, skill_version, exit_code, occurrence_count, status, timestamp, edge_case_hash FROM edge_cases WHERE skill_name = ?1 AND occurrence_count >= ?2 ORDER BY occurrence_count DESC, timestamp DESC" \
+            "$skill_name" "$RECURRENCE_THRESHOLD" | sqlite3 -header -column "$DB_PATH" ".mode column"
+    else
+        sqlite_select "$DB_PATH" \
+            "SELECT skill_name, skill_version, exit_code, occurrence_count, status, timestamp, edge_case_hash FROM edge_cases WHERE occurrence_count >= ?1 ORDER BY occurrence_count DESC, timestamp DESC" \
+            "$RECURRENCE_THRESHOLD" | sqlite3 -header -column "$DB_PATH" ".mode column"
+    fi
+}
+
+# Get edge case details
+get_edge_case_details() {
+    local edge_case_hash="$1"
+
+    # Use parameterized query with JSON output mode
+    sqlite_select "$DB_PATH" "SELECT * FROM edge_cases WHERE edge_case_hash = ?1" "$edge_case_hash" | sqlite3 -json "$DB_PATH" ".mode json"
+}
+
+# Update edge case status
+update_edge_case_status() {
+    local edge_case_hash="$1"
+    local status="$2"
+
+    # Use parameterized query for status update
+    sqlite_update "$DB_PATH" \
+        "UPDATE edge_cases SET status = ?1 WHERE edge_case_hash = ?2" \
+        "$status" "$edge_case_hash"
+    echo "Updated edge case status to: $status"
+}
+
+# Main execution
+main() {
+    # Initialize database
+    init_database
+
+    # Parse arguments
+    local action=""
+    local skill_name=""
+    local skill_version=""
+    local exit_code=""
+    local input_params=""
+    local expected_output=""
+    local actual_output=""
+    local error_message=""
+    local edge_case_hash=""
+    local metadata="{}"
+
+    while [[ $# -gt 0 ]]; do
+        case $1 in
+            --action)
+                action="$2"
+                shift 2
+                ;;
+            --skill-name)
+                skill_name="$2"
+                shift 2
+                ;;
+            --skill-version)
+                skill_version="$2"
+                shift 2
+                ;;
+            --exit-code)
+                exit_code="$2"
+                shift 2
+                ;;
+            --input-params)
+                input_params="$2"
+                shift 2
+                ;;
+            --expected-output)
+                expected_output="$2"
+                shift 2
+                ;;
+            --actual-output)
+                actual_output="$2"
+                shift 2
+                ;;
+            --error-message)
+                error_message="$2"
+                shift 2
+                ;;
+            --edge-case-hash)
+                edge_case_hash="$2"
+                shift 2
+                ;;
+            --metadata)
+                metadata="$2"
+                shift 2
+                ;;
+            --help)
+                cat <<HELP
+Usage: track-edge-case.sh --action <ACTION> [OPTIONS]
+
+Actions:
+  record           Record a new edge case
+  query            Query recurring edge cases
+  details          Get edge case details
+  update-status    Update edge case status
+
+Record Options:
+  --skill-name STRING         Skill name (required)
+  --skill-version STRING      Skill version (required)
+  --exit-code INTEGER         Exit code (required)
+  --input-params STRING       Input parameters (required)
+  --expected-output STRING    Expected output (optional)
+  --actual-output STRING      Actual output (optional)
+  --error-message STRING      Error message (optional)
+  --metadata JSON             Additional metadata (optional)
+
+Query Options:
+  --skill-name STRING         Filter by skill name (optional)
+
+Details Options:
+  --edge-case-hash STRING     Edge case hash (required)
+
+Update Status Options:
+  --edge-case-hash STRING     Edge case hash (required)
+  --status STRING             New status (new|analyzing|proposal_generated|resolved)
+
+Environment Variables:
+  DB_PATH                     Path to SQLite database (default: ./workflow-codification.db)
+
+Examples:
+  # Record edge case
+  track-edge-case.sh --action record \\
+    --skill-name "cfn-coordination" \\
+    --skill-version "1.0.0" \\
+    --exit-code 1 \\
+    --input-params "task-id=123 timeout=30" \\
+    --error-message "Connection timeout"
+
+  # Query recurring edge cases
+  track-edge-case.sh --action query --skill-name "cfn-coordination"
+
+  # Get edge case details
+  track-edge-case.sh --action details --edge-case-hash "abc123..."
+
+  # Update edge case status
+  track-edge-case.sh --action update-status \\
+    --edge-case-hash "abc123..." \\
+    --status "proposal_generated"
+HELP
+                exit 0
+                ;;
+            *)
+                echo "Unknown argument: $1" >&2
+                exit 1
+                ;;
+        esac
+    done
+
+    # Execute action
+    case "$action" in
+        record)
+            if [[ -z "$skill_name" || -z "$skill_version" || -z "$exit_code" || -z "$input_params" ]]; then
+                echo "Error: --skill-name, --skill-version, --exit-code, and --input-params are required" >&2
+                exit 1
+            fi
+            record_edge_case "$skill_name" "$skill_version" "$exit_code" "$input_params" \
+                "$expected_output" "$actual_output" "$error_message" "$metadata"
+            ;;
+        query)
+            query_recurring_edge_cases "$skill_name"
+            ;;
+        details)
+            if [[ -z "$edge_case_hash" ]]; then
+                echo "Error: --edge-case-hash is required" >&2
+                exit 1
+            fi
+            get_edge_case_details "$edge_case_hash"
+            ;;
+        update-status)
+            if [[ -z "$edge_case_hash" ]]; then
+                echo "Error: --edge-case-hash is required" >&2
+                exit 1
+            fi
+            update_edge_case_status "$edge_case_hash" "$status"
+            ;;
+        *)
+            echo "Error: Invalid action. Use --help for usage information." >&2
+            exit 1
+            ;;
+    esac
+}
+
+# Execute main if not sourced
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi

package/.claude/skills/cfn-local-ruvector-accelerator/AGENT_LIFECYCLE_INTEGRATION.md

@@ -0,0 +1,341 @@
+# RuVector Agent Lifecycle Integration
+
+## Overview
+
+The RuVector Agent Lifecycle Integration automatically captures and indexes agent execution data, enabling semantic search over historical agent decisions, tool usage patterns, and failure recovery strategies.
+
+## Architecture
+
+```
+Agent Execution → cfn-subagent-stop.sh → ingest-agent-transcript.sh → SQLite Database
+                                                                      ↓
+                                                           agent_transcripts
+                                                           agent_failure_patterns
+                                                                      ↓
+                                                          query-agent-patterns.sh
+```
+
+## Components
+
+### 1. Transcript Ingestion (`ingest-agent-transcript.sh`)
+
+Automatically called by `cfn-subagent-stop.sh` after each agent execution.
+
+**Functionality:**
+- Parses JSONL transcript files
+- Extracts decision points and tool usage events
+- Identifies error patterns in failed agents
+- Stores searchable snippets in `agent_transcripts` table
+
+**Schema:**
+```sql
+CREATE TABLE agent_transcripts (
+    id TEXT PRIMARY KEY,
+    agent_id TEXT NOT NULL,
+    agent_type TEXT NOT NULL,
+    task_id TEXT,
+    snippet TEXT NOT NULL,
+    snippet_type TEXT,           -- decision, tool_use, error, recovery
+    embedding BLOB,               -- placeholder for future vector embeddings
+    metadata TEXT,                -- JSON: tool, outcome, timestamp, line_number
+    success_rate REAL DEFAULT 0.0,
+    usage_count INTEGER DEFAULT 0,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+### 2. Failure Pattern Analysis (`analyze-agent-failures.sh`)
+
+Periodic analysis of agent failures to identify common patterns and recovery strategies.
+
+**Usage:**
+```bash
+# Analyze failures from last 7 days
+./analyze-agent-failures.sh --days 7
+
+# Analyze failures from last 30 days, minimum 3 occurrences
+./analyze-agent-failures.sh --days 30 --min-occurrences 3
+```
+
+**Functionality:**
+- Queries failed agents (confidence < 0.70 or explicit failure)
+- Classifies failure modes: edit_hook_validation, timeout, permission_error, syntax_error, test_failure
+- Clusters similar failures
+- Identifies recovery strategies from subsequent successful executions
+- Updates `agent_failure_patterns` table
+
+**Schema:**
+```sql
+CREATE TABLE agent_failure_patterns (
+    id TEXT PRIMARY KEY,
+    agent_type TEXT NOT NULL,
+    failure_mode TEXT NOT NULL,
+    root_cause TEXT,
+    recovery_strategy TEXT,
+    embedding BLOB,
+    occurrence_count INTEGER DEFAULT 1,
+    last_seen TIMESTAMP,
+    resolution_rate REAL DEFAULT 0.0,
+    metadata TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+### 3. Pattern Query Interface (`query-agent-patterns.sh`)
+
+Search historical agent data for guidance on current tasks.
+
+**Usage:**
+```bash
+# Search all patterns
+./query-agent-patterns.sh --query "pre-edit hook validation failure"
+
+# Search only failure patterns
+./query-agent-patterns.sh --query "validation" --search-type failures
+
+# Filter by agent type
+./query-agent-patterns.sh --query "file write" --type coder --limit 5
+
+# Get statistics
+./query-agent-patterns.sh --search-type stats
+```
+
+**Search Types:**
+- `all` - Search both transcripts and failure patterns (default)
+- `transcripts` - Search only agent transcript snippets
+- `failures` - Search only failure patterns
+- `stats` - Display agent lifecycle statistics
+
+## Integration with cfn-subagent-stop.sh
+
+The subagent stop hook automatically triggers RuVector ingestion:
+
+```bash
+# cfn-subagent-stop.sh (excerpt)
+
+# Determine agent success/failure
+AGENT_SUCCESS="true"
+AGENT_CONFIDENCE=$(sqlite3 "$DB_PATH" "SELECT confidence FROM agents WHERE id = '$AGENT_ID';")
+
+if awk "BEGIN {exit !($AGENT_CONFIDENCE < 0.70)}"; then
+    AGENT_SUCCESS="false"
+fi
+
+# Call RuVector ingestion
+./.claude/skills/cfn-local-ruvector-accelerator/ingest-agent-transcript.sh \
+    --transcript "$TRANSCRIPT_ARCHIVE" \
+    --agent-id "$AGENT_ID" \
+    --agent-type "$AGENT_TYPE" \
+    --task-id "$TASK_ID" \
+    --success "$AGENT_SUCCESS"
+```
+
+## Data Flow
+
+### Phase 1: Transcript Ingestion (Automatic)
+
+1. Agent completes execution
+2. `cfn-subagent-stop.sh` hook fires
+3. Transcript copied to `.artifacts/transcripts/`
+4. `ingest-agent-transcript.sh` called automatically
+5. JSONL parsed for tool_use and error events
+6. Snippets stored in `agent_transcripts` table
+7. Agent metadata updated with processing status
+
+### Phase 2: Failure Pattern Analysis (Periodic)
+
+1. Run `analyze-agent-failures.sh` weekly/monthly
+2. Query failed agents from lifecycle database
+3. Extract failure contexts from transcripts
+4. Classify and cluster failure modes
+5. Identify recovery strategies from successful agents
+6. Store patterns in `agent_failure_patterns` table
+
+### Phase 3: Pattern Query (On-Demand)
+
+1. Developer/agent encounters issue
+2. Query historical patterns: `./query-agent-patterns.sh --query "similar issue"`
+3. Review matched transcripts and failure patterns
+4. Apply recovery strategies from historical successes
+
+## Example Queries
+
+### Find validation failure solutions
+```bash
+./query-agent-patterns.sh --query "validation failed" --search-type failures
+```
+
+Output:
+```
+=== Failure Pattern Matches ===
+
+Agent Type: loop3-implementer
+Failure Mode: edit_hook_validation
+Occurrences: 12
+Root Cause: pre-edit backup hook failed: file permissions on /tmp/...
+Recovery Strategy: Successful loop3-implementer agents: used similar tool chains with validation steps
+```
+
+### Find tool usage patterns for file operations
+```bash
+./query-agent-patterns.sh --query "write file" --type coder --limit 5
+```
+
+Output:
+```
+=== Agent Transcript Matches ===
+
+Agent: agent-20241209-001 (coder)
+Type: tool_use
+Snippet: {"type":"tool_use","name":"Write","input":{"file_path":"/path/to/file.ts","content":"..."},...
+Metadata: {"tool":"Write","outcome":"true","line_number":42,"timestamp":"2024-12-09T10:30:00Z"}
+```
+
+### Get agent statistics
+```bash
+./query-agent-patterns.sh --search-type stats
+```
+
+Output:
+```
+=== Agent Lifecycle Statistics ===
+
+Agent executions by type:
+loop3-implementer|145
+loop2-validator|98
+coder|67
+...
+
+Recent failures (last 7 days):
+8
+
+Most common failure modes:
+edit_hook_validation|15
+timeout|7
+test_failure|5
+```
+
+## Future Enhancements
+
+### Vector Embeddings (Phase 4)
+
+Currently, the `embedding BLOB` field is a placeholder. Future integration with actual vector embeddings:
+
+1. **Use sentence-transformers** for semantic search:
+   ```python
+   from sentence_transformers import SentenceTransformer
+   model = SentenceTransformer('all-MiniLM-L6-v2')
+   embedding = model.encode(snippet_text)
+   ```
+
+2. **Store embeddings** in the BLOB field
+3. **Query by similarity** using cosine distance
+4. **Enable questions like**: "What did agents do when encountering TypeScript type errors?"
+
+### Tool Pattern Learning (Phase 5)
+
+Track successful tool combinations:
+
+```sql
+CREATE TABLE tool_patterns (
+    id TEXT PRIMARY KEY,
+    agent_type TEXT NOT NULL,
+    tool_sequence TEXT NOT NULL,  -- "Bash,Glob,Grep,Write,Bash"
+    success_rate REAL DEFAULT 0.0,
+    usage_count INTEGER DEFAULT 0,
+    avg_duration_ms REAL,
+    metadata TEXT
+);
+```
+
+### Confidence Calibration (Phase 6)
+
+Track reported vs. actual confidence:
+
+```sql
+CREATE TABLE confidence_calibration (
+    id TEXT PRIMARY KEY,
+    agent_type TEXT NOT NULL,
+    confidence_reported REAL NOT NULL,
+    confidence_actual REAL NOT NULL,
+    context_size INTEGER,
+    outcome TEXT
+);
+```
+
+## Maintenance
+
+### Database Size Management
+
+Monitor database growth:
+```bash
+du -h .claude/skills/cfn-redis-coordination/data/cfn-loop.db
+```
+
+Archive old transcripts:
+```bash
+# Archive transcripts older than 90 days
+sqlite3 "$DB_PATH" "DELETE FROM agent_transcripts WHERE created_at < datetime('now', '-90 days');"
+
+# Archive old failure patterns with low occurrence
+sqlite3 "$DB_PATH" "DELETE FROM agent_failure_patterns WHERE occurrence_count < 2 AND created_at < datetime('now', '-30 days');"
+```
+
+### Log Management
+
+RuVector ingestion logs are written to:
+- `.artifacts/logs/ruvector-ingestion.log` - Transcript ingestion events
+- `.artifacts/logs/ruvector-failure-analysis.log` - Failure pattern analysis
+- `.artifacts/logs/subagent-lifecycle.log` - Hook execution logs
+
+Rotate logs periodically:
+```bash
+# Rotate logs older than 30 days
+find .artifacts/logs -name "*.log" -mtime +30 -delete
+```
+
+## Troubleshooting
+
+### Ingestion not running
+
+Check if hook is being called:
+```bash
+tail -f .artifacts/logs/subagent-lifecycle.log
+```
+
+Verify script exists and is executable:
+```bash
+ls -l .claude/skills/cfn-local-ruvector-accelerator/ingest-agent-transcript.sh
+```
+
+### No patterns found
+
+Run failure analysis manually:
+```bash
+./.claude/skills/cfn-local-ruvector-accelerator/analyze-agent-failures.sh --days 30
+```
+
+Check database tables exist:
+```bash
+sqlite3 .claude/skills/cfn-redis-coordination/data/cfn-loop.db ".tables"
+```
+
+### Query returns no results
+
+Check if data exists:
+```bash
+sqlite3 .claude/skills/cfn-redis-coordination/data/cfn-loop.db "SELECT COUNT(*) FROM agent_transcripts;"
+sqlite3 .claude/skills/cfn-redis-coordination/data/cfn-loop.db "SELECT COUNT(*) FROM agent_failure_patterns;"
+```
+
+Run with broader query:
+```bash
+./query-agent-patterns.sh --query "error" --limit 20
+```
+
+## References
+
+- Analysis document: `docs/RUVECTOR_INTEGRATION_ANALYSIS.md`
+- Subagent hooks: `.claude/hooks/cfn-subagent-*.sh`
+- RuVector accelerator: `.claude/skills/cfn-local-ruvector-accelerator/`
+- Lifecycle database: `.claude/skills/cfn-redis-coordination/data/cfn-loop.db`

package/.claude/skills/cfn-local-ruvector-accelerator/Cargo.toml

@@ -0,0 +1,40 @@
+[package]
+name = "local-ruvector"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+# Database
+rusqlite = { version = "0.31", features = ["bundled", "vtab"] }
+# Vector operations
+ndarray = { version = "0.15", features = ["rayon"], default-features = false }
+# Serialization
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+# CLI
+clap = { version = "4.4", features = ["derive"] }
+anyhow = "1.0"
+# File system
+walkdir = "2.4"
+# Hashing
+sha2 = "0.10"
+# Async (for embedding API)
+tokio = { version = "1.0", features = ["full"] }
+reqwest = { version = "0.11", features = ["json"] }
+# Logging
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["json", "env-filter"] }
+# Parallel processing
+rayon = "1.8"
+# Memory mapping
+memmap2 = "0.9"
+# Binary serialization
+byteorder = "1.5"
+# Regular expressions
+regex = "1.10"
+# Date/time
+chrono = { version = "0.4", features = ["serde"] }
+# File operations
+fs_extra = "1.3"
+# Environment
+dotenvy = "0.15"