@nockdev/awf 6.2.0

package/.agent/core/HSA.yaml

@@ -0,0 +1,357 @@
+# =============================================================================
+# HSA.yaml — Hierarchical Skills Architecture v1.0.0 Master Config
+# =============================================================================
+# DOMYH Awesome Code Agent — Context-Aware Neural-Symbolic Hierarchy
+# Version: 1.0.0
+# Date: 2026-02-05
+# =============================================================================
+
+# =============================================================================
+# SYSTEM OVERVIEW
+# =============================================================================
+
+version: "1.0.0"
+codename: "Context Mesh"
+architecture: "CANSH v2.0" # Context-Aware Neural-Symbolic Hierarchy
+
+description: |
+  HSA v1.0.0 implements advanced context engineering with:
+  - HybridRAG+ with ColBERT-style reranking (MaxSim)
+  - Merkle-bound embedding cache (11x speedup)
+  - AST-based semantic chunking (tree-sitter)
+  - Dynamic Leiden community detection (incremental)
+  - GPU acceleration (cuGraph + batch embeddings)
+  - Proactive prefetching with trajectory prediction
+  - Mark-and-sweep garbage collection
+
+# =============================================================================
+# LAYER ARCHITECTURE
+# =============================================================================
+
+layers:
+  layer_0:
+    name: "Attention Sink"
+    type: "immutable"
+    description: "Protected tokens for attention stability"
+    token_budget: 500
+    components:
+      - system_prompt # Core instructions
+      - security_policies # Safety rules
+      - core_rules # Constitutional rules
+    refresh: "never"
+    research_source: "StreamingLLM (ICLR 2024)"
+
+  layer_1:
+    name: "Project Profile"
+    type: "static"
+    description: "Cached project metadata with Merkle validation"
+    token_budget: 300
+    components:
+      - stack_detection # Scoring-based tech detection
+      - skill_metas # Detected skill summaries
+      - graph_hash # Merkle root for validation
+    refresh: "on_merkle_change"
+    research_source: "Cursor IDE (2025)"
+
+  layer_2:
+    name: "HiRAG Context"
+    type: "dynamic"
+    description: "3-level hierarchical retrieval"
+    token_budget:
+      min: 1000
+      max: 2000
+    components:
+      global_context:
+        description: "Community summaries"
+        algorithm: "Leiden clustering"
+      bridge_context:
+        description: "Entity connections via shortest path"
+        algorithm: "Dijkstra + path merge"
+      local_context:
+        description: "Entity descriptions"
+        algorithm: "Top-k entity retrieval"
+    refresh: "per_query"
+    research_source: "HiRAG (ACL 2025)"
+
+  layer_3:
+    name: "JIT Code"
+    type: "just_in_time"
+    description: "On-demand code loading with budget awareness"
+    token_budget:
+      min: 1500
+      max: 3000
+    components:
+      - skill_content # Selected SKILL.md content
+      - file_chunks # Hot region prioritized
+      - prefetch_cache # Predicted next files
+    refresh: "per_action"
+    features:
+      - priority_truncation
+      - semantic_chunking
+
+  layer_4:
+    name: "Compressed History"
+    type: "sliding"
+    description: "GC-managed conversation history"
+    token_budget:
+      min: 500
+      max: 1000
+    components:
+      - summarized_actions # Past action summaries
+      - key_decisions # Retained important choices
+      - recent_trajectory # Last 5 actions (protected)
+    refresh: "mark_and_sweep"
+    research_source: "AttentionRAG (OpenReview 2025)"
+
+# =============================================================================
+# TOKEN BUDGET MANAGEMENT
+# =============================================================================
+
+token_budget:
+  total: 8000
+
+  allocation:
+    sink: 500 # Protected, never evict
+    project: 300 # Cached profile
+    hirag: 2000 # Context retrieval
+    jit: 3000 # Code chunks
+    history: 1000 # Compressed history
+    response: 2000 # Output buffer (not in context)
+
+  complexity_multipliers:
+    simple: 0.6 # Simple queries, reduce JIT/HiRAG
+    medium: 1.0 # Default
+    complex: 1.5 # Expand JIT/HiRAG, compress history
+
+  overflow_strategy:
+    1: "truncate_jit" # First: reduce code chunks
+    2: "compress_history" # Then: summarize history
+    3: "reduce_hirag_levels" # Finally: skip bridge context
+
+# =============================================================================
+# MERKLE TREE CONFIGURATION
+# =============================================================================
+
+merkle_tree:
+  enabled: true
+  algorithm: "blake3"
+
+  watch:
+    debounce_ms: 500 # Debounce rapid changes
+    poll_interval_ms: 300000 # Full check every 5 minutes
+
+  ignore_patterns:
+    - "node_modules/**"
+    - ".git/**"
+    - "__pycache__/**"
+    - "*.pyc"
+    - "dist/**"
+    - "build/**"
+    - ".agent/memory/**" # Memory is separate
+
+  chunk_strategy:
+    parser: "tree-sitter" # AST-based chunking
+    max_chunk_tokens: 500
+    overlap_lines: 3
+
+# =============================================================================
+# STACK DETECTION
+# =============================================================================
+
+stack_detection:
+  mode: "scoring" # "scoring" | "binary"
+
+  weights:
+    file_pattern: 10 # .sln, Cargo.toml, etc.
+    dependency: 8 # package.json deps
+    extension_frequency: 5 # .go, .py counts (log scale)
+
+  threshold: 0.3 # Minimum score ratio
+  max_skills: 5 # Top N skills to load
+
+  rules_file: "detection_rules.yaml"
+
+# =============================================================================
+# HIRAG CONFIGURATION
+# =============================================================================
+
+hirag:
+  enabled: true
+
+  community:
+    algorithm: "leiden" # Leiden community detection
+    resolution: 1.0
+    min_size: 3
+
+  retrieval:
+    global_k: 3 # Top communities
+    local_k: 5 # Top entities
+    bridge_enabled: true # Enable shortest path
+
+  embedding:
+    model: "text-embedding-3-small"
+    dimension: 1536
+    batch_size: 100
+
+# =============================================================================
+# PREFETCHING
+# =============================================================================
+
+prefetching:
+  enabled: true
+
+  strategies:
+    graph_based:
+      enabled: true
+      relations: ["imports", "calls", "tests", "types"]
+      max_candidates: 3
+
+    trajectory_based:
+      enabled: true
+      model: "markov" # Simple Markov chain
+      history_length: 10
+      max_predictions: 2
+
+  cache:
+    max_size: 50 # LRU cache size
+    ttl_seconds: 300 # 5 minute TTL
+
+  async: true # Non-blocking prefetch
+
+# =============================================================================
+# GARBAGE COLLECTION
+# =============================================================================
+
+garbage_collection:
+  enabled: true
+  algorithm: "mark_and_sweep"
+
+  protected:
+    - "attention_sink" # Never evict (first 4 tokens)
+    - "current_query" # Current user request
+    - "pinned_context" # User-marked important
+    - "recent_actions" # Last 5 actions
+
+  summarization:
+    trigger_threshold: 1000 # Tokens before summarization
+    target_size: 500 # Compress to this size
+    preserve_decisions: true # Keep key decisions
+
+  sweep_interval: "per_turn" # When to run GC
+
+# =============================================================================
+# ERROR RECOVERY
+# =============================================================================
+
+error_recovery:
+  merkle_corruption:
+    action: "rebuild_tree"
+    notify_user: false
+
+  graph_stale:
+    action: "incremental_update"
+    fallback: "full_rebuild"
+
+  jit_empty:
+    fallback_chain:
+      - "git_history" # Try HEAD~1
+      - "semantic_search" # Find similar
+      - "ask_user" # Last resort
+
+  router_low_confidence:
+    threshold: 0.7
+    action: "user_confirmation"
+
+# =============================================================================
+# METRICS & OBSERVABILITY
+# =============================================================================
+
+metrics:
+  enabled: true
+
+  tracked:
+    cer:
+      description: "Context Efficiency Ratio"
+      formula: "modified_tokens / total_loaded"
+      target: 0.5
+
+    ttfa:
+      description: "Time to First Action"
+      components: ["intent", "validation", "retrieval", "assembly"]
+      target_ms: 500
+
+    localization:
+      description: "File Localization Accuracy"
+      formula: "correct_files / total_attempts"
+      target: 0.6
+
+    token_savings:
+      description: "Baseline Token Reduction"
+      formula: "(baseline - actual) / baseline"
+      target: 0.9
+
+  export:
+    format: "prometheus"
+    endpoint: "/metrics"
+
+# =============================================================================
+# MODULE PATHS
+# =============================================================================
+
+modules:
+  base_path: ".agent/scripts/hsa"
+
+  # Core v1.0.0 modules
+  files:
+    merkle_tree: "merkle_tree.py"
+    file_hasher: "file_hasher.py"
+    change_detector: "change_detector.py"
+    project_detector: "detection/project_detector.py"
+    detection_rules: "detection_rules.yaml"
+    hirag_retriever: "hirag_retriever.py"
+    community_graph: "retrieval/community_graph_v4.py"
+    bridge_finder: "bridge_finder.py"
+    token_budget: "token_budget.py"
+    context_gc: "context_gc.py"
+    smart_truncation: "smart_truncation.py"
+    prefetcher: "prefetcher.py"
+    trajectory_model: "trajectory_model.py"
+    engine: "engine/__init__.py"
+    tests: "tests/test_hsa_v4.py"
+
+  # v1.0.0 Enhancement modules
+  v7_modules:
+    reranker: "retrieval/reranker.py" # ColBERT + CrossEncoder
+    embedding_cache: "cache/embedding_cache.py" # Merkle-bound LRU cache
+    ast_chunker: "chunking/ast_chunker.py" # Tree-sitter AST chunking
+    gpu_accelerator: "engine/gpu_accelerator.py" # cuGraph + GPU embeddings
+    hybrid_search: "retrieval/hybrid.py" # HybridRAG+ 3-stage pipeline
+
+# =============================================================================
+# FEATURE FLAGS
+# =============================================================================
+
+feature_flags:
+  # v1.0.0 features
+  merkle_indexing: true
+  scoring_detection: true
+  hirag_3level: true
+  adaptive_budget: true
+  proactive_prefetch: true
+  mark_sweep_gc: true
+  trajectory_prediction: false # Phase 5
+  bridge_context: true
+
+  # v1.0.0 features
+  colbert_reranking: true # MaxSim reranking
+  embedding_cache: true # Merkle-bound cache
+  ast_chunking: true # Tree-sitter chunking
+  gpu_acceleration: false # Optional (requires cuGraph)
+  dynamic_leiden: true # Incremental community detection
+
+
+# =============================================================================
+# FOOTER
+# =============================================================================
+# _DOMYH Awesome Code • HSA v1.0.0 • Context Mesh_
+

package/.agent/core/HYBRID_ROUTER.yaml

@@ -0,0 +1,346 @@
+# =============================================================================
+# DOMYH Awesome Code
+# Hybrid Router - Multi-Strategy Semantic Routing
+# =============================================================================
+
+version: "6.1.2"
+
+# =============================================================================
+# OVERVIEW
+# Combines TF-IDF, embeddings, and intent classification for optimal routing
+# =============================================================================
+
+description: |
+  The Hybrid Router uses multiple strategies to route queries to skills:
+  1. TF-IDF (keyword matching) - Fast, good for exact terms
+  2. Embeddings (semantic similarity) - Deep meaning understanding
+  3. Intent Classifier - High-level intent routing
+  4. Pattern Matching - Fallback for explicit patterns
+
+# =============================================================================
+# STRATEGY CONFIGURATION
+# =============================================================================
+
+strategies:
+  # ---------------------------------------------------------------------------
+  # TF-IDF Strategy (existing, enhanced)
+  # ---------------------------------------------------------------------------
+  tfidf:
+    enabled: true
+    weight: 0.25
+
+    description: "Keyword-based matching using TF-IDF vectors"
+
+    config:
+      tokenizer: "word"
+      lowercase: true
+      remove_stopwords: true
+      min_term_frequency: 1
+      max_document_frequency: 0.9
+
+    use_for:
+      - "Exact term matching"
+      - "Technical keywords"
+      - "Command detection"
+
+    scoring:
+      source_weights:
+        name: 0.3
+        description: 0.25
+        keywords: 0.25
+        detect_patterns: 0.2
+
+  # ---------------------------------------------------------------------------
+  # Embedding Strategy (NEW)
+  # ---------------------------------------------------------------------------
+  embedding:
+    enabled: true
+    weight: 0.40
+
+    description: "Semantic similarity using vector embeddings"
+
+    config:
+      model: "all-MiniLM-L6-v2" # Local model
+      dimensions: 384
+      normalize: true
+      cache_enabled: true
+      cache_path: ".agent/cache/embeddings/"
+
+    use_for:
+      - "Semantic meaning"
+      - "Synonyms and related concepts"
+      - "Natural language queries"
+
+    fallback_model: "tfidf" # If embedding fails
+
+    precompute:
+      on_startup: true
+      skills_to_embed:
+        - "name"
+        - "description"
+        - "keywords"
+        - "examples"
+
+  # ---------------------------------------------------------------------------
+  # Intent Classifier (NEW)
+  # ---------------------------------------------------------------------------
+  intent:
+    enabled: true
+    weight: 0.25
+
+    description: "High-level intent classification"
+
+    config:
+      method: "rule_based" # Options: rule_based, ml_classifier
+
+    intents:
+      code:
+        patterns:
+          - "create"
+          - "implement"
+          - "write"
+          - "add"
+          - "build"
+        skills_boost: ["typescript", "python", "go", "react", "vue"]
+
+      debug:
+        patterns:
+          - "fix"
+          - "debug"
+          - "error"
+          - "bug"
+          - "issue"
+        skills_boost: ["testing", "security"]
+
+      refactor:
+        patterns:
+          - "refactor"
+          - "improve"
+          - "optimize"
+          - "clean"
+        skills_boost: ["coding-rules"]
+
+      deploy:
+        patterns:
+          - "deploy"
+          - "release"
+          - "production"
+          - "ci/cd"
+        skills_boost: ["docker", "kubernetes", "ci-cd"]
+
+      review:
+        patterns:
+          - "review"
+          - "check"
+          - "audit"
+          - "analyze"
+        skills_boost: ["security", "testing", "coding-rules"]
+
+      learn:
+        patterns:
+          - "how to"
+          - "what is"
+          - "explain"
+          - "tutorial"
+        skills_boost: [] # No specific boost
+
+  # ---------------------------------------------------------------------------
+  # Pattern Matching (fallback)
+  # ---------------------------------------------------------------------------
+  pattern:
+    enabled: true
+    weight: 0.10
+
+    description: "Explicit pattern matching fallback"
+
+    patterns:
+      # Direct skill mentions
+      skill_mention:
+        regex: "@(\\w+)"
+        action: "load_skill_by_name"
+
+      # Command patterns
+      commands:
+        regex: "^/(\\w+)"
+        action: "route_to_workflow"
+
+      # File type detection
+      file_types:
+        regex: "\\.(ts|js|py|go|rs|java|cpp|c|rb|php)\\b"
+        action: "boost_language_skill"
+
+# =============================================================================
+# SELECTION ALGORITHM
+# =============================================================================
+
+selection:
+  # How to combine scores from different strategies
+  combination:
+    method: "weighted_sum"
+    normalize: true
+
+  # Selection parameters
+  top_k: 5
+  min_score: 0.30
+
+  # Context-aware boosting
+  boosts:
+    # Boost recently used skills
+    recent_usage:
+      enabled: true
+      weight: 0.10
+      decay: "exponential"
+      half_life: "5 queries"
+
+    # Boost skills matching current project type
+    project_context:
+      enabled: true
+      weight: 0.15
+
+    # Boost core skills
+    core_skills:
+      enabled: true
+      weight: 0.05
+      skills: ["coding-rules", "security", "testing"]
+
+  # Diversity in results
+  diversity:
+    enabled: true
+    method: "maximal_marginal_relevance"
+    lambda: 0.7 # Balance relevance vs diversity
+
+# =============================================================================
+# QUERY PREPROCESSING
+# =============================================================================
+
+preprocessing:
+  steps:
+    1_normalize:
+      - "lowercase"
+      - "remove_extra_whitespace"
+      - "expand_abbreviations"
+
+    2_extract:
+      - "named_entities"
+      - "programming_languages"
+      - "file_paths"
+      - "error_types"
+
+    3_enrich:
+      - "add_synonyms"
+      - "expand_acronyms"
+
+  abbreviations:
+    ts: "typescript"
+    js: "javascript"
+    py: "python"
+    rb: "ruby"
+    rs: "rust"
+    k8s: "kubernetes"
+
+  synonyms:
+    test:
+      - "testing"
+      - "unit test"
+      - "spec"
+    deploy:
+      - "deployment"
+      - "release"
+      - "ship"
+    fix:
+      - "debug"
+      - "repair"
+      - "resolve"
+
+# =============================================================================
+# QUERY ROUTING
+# =============================================================================
+
+routing:
+  # Route to different handlers based on query type
+  routes:
+    simple_query:
+      condition: "len(query) < 50 AND no_code_request"
+      handler: "single_skill"
+
+    complex_query:
+      condition: "len(query) >= 50 OR multiple_topics"
+      handler: "multi_skill_ensemble"
+
+    code_request:
+      condition: "contains_code_intent"
+      handler: "code_focused"
+
+    ambiguous:
+      condition: "max_score < 0.4"
+      handler: "clarification"
+
+  handlers:
+    single_skill:
+      description: "Route to single best skill"
+      action: "return top_1"
+
+    multi_skill_ensemble:
+      description: "Combine multiple skills"
+      action: "return top_k weighted ensemble"
+
+    code_focused:
+      description: "Prioritize language-specific skills"
+      action: "filter to code skills, return top_3"
+
+    clarification:
+      description: "Ask user for clarification"
+      action: "show options to user"
+
+# =============================================================================
+# CACHING
+# =============================================================================
+
+caching:
+  enabled: true
+
+  query_cache:
+    max_size: 1000
+    ttl: "1 hour"
+    key: "query_hash"
+
+  embedding_cache:
+    max_size: 500
+    ttl: "1 day"
+    preload: true
+
+  result_cache:
+    max_size: 200
+    ttl: "5 minutes"
+
+# =============================================================================
+# METRICS & LOGGING
+# =============================================================================
+
+metrics:
+  track:
+    - "query_latency_ms"
+    - "strategy_scores"
+    - "selected_skills"
+    - "user_acceptance_rate"
+
+  log_level: "info"
+
+  export:
+    format: "json"
+    location: ".agent/memory/metrics/router/"
+
+# =============================================================================
+# A/B TESTING
+# =============================================================================
+
+ab_testing:
+  enabled: false
+
+  experiments:
+    embedding_weight:
+      variants:
+        control: 0.40
+        variant_a: 0.50
+        variant_b: 0.60
+      metric: "user_acceptance_rate"