ruvnet-kb-first 5.0.0

package/phases/01-storage.md

@@ -0,0 +1,194 @@
+# Phase 1: Storage Setup
+
+## Purpose
+
+Ensure persistent storage is available before any KB work begins. The KB must survive restarts, be queryable, and support vector embeddings.
+
+---
+
+## Prerequisites
+
+- Docker installed
+- Port 5432 available (or choose different port)
+- ~1GB disk space for initial setup
+
+---
+
+## Steps
+
+### 1.1 Check for Running Storage
+
+```bash
+docker ps | grep ruvector-db
+```
+
+**If found:** Skip to Step 1.3  
+**If not found:** Continue to Step 1.2
+
+---
+
+### 1.2 Start Persistent Storage
+
+```bash
+# Create data directory for persistence
+mkdir -p ~/ruvector-data
+
+# Start RuVector PostgreSQL
+docker run -d \
+  --name ruvector-db \
+  --restart unless-stopped \
+  -e POSTGRES_PASSWORD=${RUVECTOR_PASSWORD:-ruvector_secure_2024} \
+  -p 5432:5432 \
+  -v ~/ruvector-data:/var/lib/postgresql/data \
+  ruvnet/ruvector-postgres:latest
+```
+
+Wait for container to be healthy:
+```bash
+echo "Waiting for PostgreSQL to be ready..."
+until docker exec ruvector-db pg_isready -U postgres 2>/dev/null; do
+  sleep 2
+  echo "Still waiting..."
+done
+echo "PostgreSQL is ready!"
+```
+
+**Alternative: Standard pgvector**
+
+If ruvector-postgres is unavailable:
+```bash
+docker run -d \
+  --name ruvector-db \
+  --restart unless-stopped \
+  -e POSTGRES_PASSWORD=${RUVECTOR_PASSWORD:-ruvector_secure_2024} \
+  -p 5432:5432 \
+  -v ~/ruvector-data:/var/lib/postgresql/data \
+  pgvector/pgvector:pg16
+```
+
+---
+
+### 1.3 Verify Connection
+
+```bash
+# Set environment variable
+export DATABASE_URL="postgresql://postgres:${RUVECTOR_PASSWORD:-ruvector_secure_2024}@localhost:5432/postgres"
+
+# Test connection
+psql "$DATABASE_URL" -c "SELECT 1" || {
+  echo "ERROR: Could not connect to database"
+  exit 1
+}
+
+echo "Connection successful!"
+```
+
+---
+
+### 1.4 Initialize Schema
+
+```bash
+# Run the schema initialization
+psql "$DATABASE_URL" -f templates/schema.sql
+```
+
+**What the schema creates:**
+- `kb_nodes` — Knowledge content with embeddings
+- `kb_gaps` — Unanswered queries for KB improvement
+- `kb_analytics` — Usage tracking
+- `reasoning_bank` — SONA pattern storage
+- `gnn_nodes` and `gnn_edges` — Graph structure (if using GNN)
+- `attention_experts` — Expert routing (if using MoE)
+
+---
+
+### 1.5 Set Environment Variables
+
+Add to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):
+
+```bash
+export DATABASE_URL="postgresql://postgres:${RUVECTOR_PASSWORD:-ruvector_secure_2024}@localhost:5432/postgres"
+export RUVECTOR_STORAGE="postgres"
+export RUVECTOR_EMBEDDING_MODEL="all-MiniLM-L6-v2"
+```
+
+Reload:
+```bash
+source ~/.bashrc  # or ~/.zshrc
+```
+
+---
+
+### 1.6 Verify Extensions
+
+```bash
+psql "$DATABASE_URL" -c "SELECT extname, extversion FROM pg_extension WHERE extname IN ('vector', 'ruvector', 'pg_trgm');"
+```
+
+Expected output:
+```
+ extname  | extversion 
+----------+------------
+ vector   | 0.7.0
+ pg_trgm  | 1.6
+```
+
+If `ruvector` is available (using ruvector-postgres):
+```
+ extname  | extversion 
+----------+------------
+ ruvector | 0.2.0
+ pg_trgm  | 1.6
+```
+
+---
+
+## Quality Gate Checklist
+
+Before proceeding to Phase 2, verify:
+
+- [ ] `docker ps | grep ruvector-db` shows running container
+- [ ] `psql "$DATABASE_URL" -c "SELECT 1"` succeeds
+- [ ] Schema tables exist: `psql "$DATABASE_URL" -c "\dt kb_*"`
+- [ ] Vector extension active: `SELECT extname FROM pg_extension WHERE extname = 'vector';`
+- [ ] Environment variables set
+
+---
+
+## Troubleshooting
+
+### "Connection refused"
+```bash
+# Check if container is running
+docker ps -a | grep ruvector-db
+
+# Check logs
+docker logs ruvector-db
+
+# Restart if needed
+docker restart ruvector-db
+```
+
+### "Permission denied"
+```bash
+# Fix data directory permissions
+sudo chown -R $(id -u):$(id -g) ~/ruvector-data
+```
+
+### "Port already in use"
+```bash
+# Find what's using the port
+lsof -i :5432
+
+# Or use a different port
+docker run -d --name ruvector-db ... -p 5433:5432 ...
+export DATABASE_URL="postgresql://postgres:...@localhost:5433/postgres"
+```
+
+---
+
+## Exit Criteria
+
+Storage is running, accessible, and schema is initialized.
+
+**Proceed to Phase 2: KB Creation**

package/phases/01.5-hooks-setup.md

@@ -0,0 +1,521 @@
+# Phase 1.5: RuVector Hooks Setup
+
+Updated: 2026-01-01 23:45:00 EST | Version 1.0.0
+Created: 2026-01-01 23:45:00 EST
+
+## Purpose
+
+Configure Claude Code hooks for automatic KB enforcement. Hooks ensure KB-First rules are followed throughout development by intercepting tool calls and enforcing KB consultation.
+
+---
+
+## Prerequisites
+
+- Phase 1 complete (storage running and verified)
+- Claude Code installed
+- `~/.claude/` directory exists
+
+---
+
+## Why Hooks Are Critical
+
+Without hooks, KB-First is an honor system. Developers (or Claude) can bypass KB at any time:
+
+```typescript
+// Without hooks, nothing stops this:
+const rate = 0.04;  // Hardcoded - VIOLATION!
+```
+
+With hooks installed, every Write/Edit/Bash call is intercepted:
+
+```
+PreToolUse Hook → Check KB for relevant content → Inject context or warn
+PostToolUse Hook → Record outcome → Trigger SONA learning
+SessionEnd Hook → Persist patterns → Consolidate learning
+```
+
+---
+
+## Sub-Phases
+
+| Sub-Phase | Name | Purpose |
+|-----------|------|---------|
+| 1.5.1 | Install Hooks | Install RuVector hook scripts |
+| 1.5.2 | Configure Settings | Update ~/.claude/settings.json |
+| 1.5.3 | Pre-train ReasoningBank | Seed patterns for KB enforcement |
+| 1.5.4 | Verify Functionality | Test hooks fire correctly |
+
+---
+
+## 1.5.1 Install Hooks
+
+### Option A: RuVector CLI (Recommended)
+
+```bash
+# Initialize hooks directory and scripts
+npx @ruvector/cli hooks init
+
+# Install to Claude Code settings
+npx @ruvector/cli hooks install
+```
+
+This creates:
+- `~/.claude/hooks/pre_tool_use.py`
+- `~/.claude/hooks/post_tool_use.py`
+- `~/.claude/hooks/session_end.py`
+
+### Option B: Manual Installation
+
+Create `~/.claude/hooks/` directory:
+
+```bash
+mkdir -p ~/.claude/hooks
+```
+
+Create `~/.claude/hooks/pre_tool_use.py`:
+
+```python
+#!/usr/bin/env python3
+"""
+RuVector PreToolUse Hook
+Checks KB before every tool call
+"""
+
+import json
+import sys
+import subprocess
+import os
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+        tool_name = input_data.get('tool_name', '')
+        tool_input = input_data.get('tool_input', {})
+
+        # Skip non-writing operations
+        if tool_name not in ('Edit', 'Write', 'MultiEdit'):
+            print(json.dumps({"decision": "continue"}))
+            return
+
+        file_path = tool_input.get('file_path', '')
+
+        # Only check domain files
+        if '/domain/' not in file_path and '/src/' not in file_path:
+            print(json.dumps({"decision": "continue"}))
+            return
+
+        # Query KB for relevant context
+        query = extract_query(file_path, tool_input)
+        if query:
+            kb_results = search_kb(query)
+            if kb_results:
+                guidance = format_guidance(kb_results)
+                print(json.dumps({
+                    "decision": "continue",
+                    "message": guidance
+                }))
+            else:
+                log_gap(query)
+                print(json.dumps({
+                    "decision": "continue",
+                    "message": f"⚠️ No KB content for: {query[:80]}..."
+                }))
+        else:
+            print(json.dumps({"decision": "continue"}))
+
+    except Exception as e:
+        # Fail open - don't block on hook errors
+        print(json.dumps({"decision": "continue"}))
+
+def extract_query(file_path, tool_input):
+    """Extract searchable query from file path and content"""
+    parts = file_path.split('/')
+    relevant = [p for p in parts if p not in ('src', 'domain', 'lib')]
+    return ' '.join(relevant).replace('.ts', '').replace('.js', '')
+
+def search_kb(query):
+    """Search KB via RuVector CLI"""
+    try:
+        result = subprocess.run(
+            ['npx', '@ruvector/cli', 'search', '--query', query, '--limit', '3', '--json'],
+            capture_output=True, text=True, timeout=3
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return json.loads(result.stdout)
+    except:
+        pass
+    return []
+
+def format_guidance(results):
+    """Format KB results as guidance"""
+    lines = ["📚 KB Context:"]
+    for r in results[:3]:
+        title = r.get('title', 'Unknown')
+        conf = r.get('confidence', 0)
+        lines.append(f"  • {title} ({conf:.0%})")
+    return '\n'.join(lines)
+
+def log_gap(query):
+    """Log query that found no KB results"""
+    try:
+        subprocess.run(
+            ['npx', '@ruvector/cli', 'log-gap', '--query', query[:500]],
+            capture_output=True, timeout=2
+        )
+    except:
+        pass
+
+if __name__ == '__main__':
+    main()
+```
+
+Create `~/.claude/hooks/post_tool_use.py`:
+
+```python
+#!/usr/bin/env python3
+"""
+RuVector PostToolUse Hook
+Records outcomes and triggers SONA learning
+"""
+
+import json
+import sys
+import subprocess
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+        tool_name = input_data.get('tool_name', '')
+        success = input_data.get('success', True)
+
+        # Record outcome
+        record_outcome(tool_name, success)
+
+        # Trigger SONA learning on success
+        if success and tool_name in ('Edit', 'Write'):
+            trigger_learning(tool_name)
+
+    except:
+        pass
+
+    print(json.dumps({"decision": "continue"}))
+
+def record_outcome(tool_name, success):
+    try:
+        subprocess.run([
+            'npx', '@ruvector/cli', 'record-outcome',
+            '--tool', tool_name,
+            '--success', str(success).lower()
+        ], capture_output=True, timeout=2)
+    except:
+        pass
+
+def trigger_learning(tool_name):
+    try:
+        subprocess.run([
+            'npx', '@ruvector/cli', 'sona', 'learn',
+            '--tool', tool_name,
+            '--outcome', 'positive'
+        ], capture_output=True, timeout=2)
+    except:
+        pass
+
+if __name__ == '__main__':
+    main()
+```
+
+Create `~/.claude/hooks/session_end.py`:
+
+```python
+#!/usr/bin/env python3
+"""
+RuVector SessionEnd Hook
+Persists learned patterns
+"""
+
+import json
+import sys
+import subprocess
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+        session_id = input_data.get('session_id', 'unknown')
+
+        # Checkpoint SONA state
+        subprocess.run([
+            'npx', '@ruvector/cli', 'sona', 'checkpoint',
+            '--session', session_id
+        ], capture_output=True, timeout=5)
+
+        # Consolidate patterns
+        subprocess.run([
+            'npx', '@ruvector/cli', 'sona', 'consolidate'
+        ], capture_output=True, timeout=10)
+
+    except:
+        pass
+
+    print(json.dumps({"decision": "continue"}))
+
+if __name__ == '__main__':
+    main()
+```
+
+Make hooks executable:
+
+```bash
+chmod +x ~/.claude/hooks/*.py
+```
+
+---
+
+## 1.5.2 Configure Settings
+
+Update `~/.claude/settings.json` to register hooks:
+
+### Option A: RuVector CLI
+
+```bash
+npx @ruvector/cli hooks configure
+```
+
+### Option B: Manual Configuration
+
+Edit `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/pre_tool_use.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/post_tool_use.py"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/session_end.py"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Verify configuration:
+
+```bash
+cat ~/.claude/settings.json | jq '.hooks'
+```
+
+---
+
+## 1.5.3 Pre-train ReasoningBank
+
+The ReasoningBank stores patterns that hooks use to provide guidance. Pre-training seeds it with KB-First enforcement patterns.
+
+### Option A: RuVector CLI
+
+```bash
+# Pre-train with KB-First patterns
+npx @ruvector/cli reasoningbank seed --kb-first
+
+# Or seed from this repository
+npx @ruvector/cli reasoningbank import ./patterns/kb-first-patterns.json
+```
+
+### Option B: Manual Seeding
+
+```bash
+# Connect to ReasoningBank database
+export REASONING_BANK_DB=".swarm/memory.db"
+
+# Seed KB-First patterns
+sqlite3 "$REASONING_BANK_DB" << 'EOF'
+INSERT INTO reasoning_memory (id, title, content, namespace, created_at)
+VALUES
+  (lower(hex(randomblob(16))), 'kb/enforcement/no-hardcode',
+   'Never hardcode domain values. Always query KB: const rate = await kb.search("rate")',
+   'kb_first_patterns', datetime('now')),
+  (lower(hex(randomblob(16))), 'kb/enforcement/source-return',
+   'All domain functions must return kbSources array for traceability',
+   'kb_first_patterns', datetime('now')),
+  (lower(hex(randomblob(16))), 'kb/enforcement/startup-verify',
+   'Entry point must verify KB connection with process.exit(1) on failure',
+   'kb_first_patterns', datetime('now')),
+  (lower(hex(randomblob(16))), 'kb/enforcement/no-fallback',
+   'Never use fallback defaults: const x = kbValue || DEFAULT is forbidden',
+   'kb_first_patterns', datetime('now')),
+  (lower(hex(randomblob(16))), 'kb/enforcement/expert-attribution',
+   'All KB nodes must have source_expert field with expert name',
+   'kb_first_patterns', datetime('now'));
+EOF
+```
+
+Verify seeding:
+
+```bash
+sqlite3 "$REASONING_BANK_DB" "SELECT title FROM reasoning_memory WHERE namespace = 'kb_first_patterns';"
+```
+
+Expected output:
+```
+kb/enforcement/no-hardcode
+kb/enforcement/source-return
+kb/enforcement/startup-verify
+kb/enforcement/no-fallback
+kb/enforcement/expert-attribution
+```
+
+---
+
+## 1.5.4 Verify Functionality
+
+### Test 1: Hooks Are Registered
+
+```bash
+cat ~/.claude/settings.json | jq '.hooks | keys'
+```
+
+Expected output:
+```json
+[
+  "PreToolUse",
+  "PostToolUse",
+  "SessionEnd"
+]
+```
+
+### Test 2: Hook Scripts Exist and Are Executable
+
+```bash
+ls -la ~/.claude/hooks/*.py
+
+# Test syntax
+python3 -m py_compile ~/.claude/hooks/pre_tool_use.py
+python3 -m py_compile ~/.claude/hooks/post_tool_use.py
+python3 -m py_compile ~/.claude/hooks/session_end.py
+```
+
+### Test 3: PreToolUse Hook Fires
+
+```bash
+# Simulate hook input
+echo '{"tool_name": "Write", "tool_input": {"file_path": "src/domain/calculator.ts"}}' | \
+  python3 ~/.claude/hooks/pre_tool_use.py
+```
+
+Expected output (JSON with decision):
+```json
+{"decision": "continue", "message": "..."}
+```
+
+or
+
+```json
+{"decision": "continue"}
+```
+
+### Test 4: ReasoningBank Has Patterns
+
+```bash
+sqlite3 .swarm/memory.db "SELECT COUNT(*) FROM reasoning_memory WHERE namespace = 'kb_first_patterns';"
+```
+
+Expected: `≥5`
+
+### Test 5: End-to-End Verification
+
+```bash
+# Run the verification script
+./scripts/1.5-hooks-verify.sh
+```
+
+---
+
+## Quality Gate Checklist
+
+Before proceeding to Phase 2, verify:
+
+- [ ] Hook scripts exist in `~/.claude/hooks/`
+- [ ] Hooks are registered in `~/.claude/settings.json`
+- [ ] ReasoningBank has KB-First patterns (≥5 entries)
+- [ ] PreToolUse hook returns valid JSON
+- [ ] All hook scripts pass syntax check
+- [ ] `./scripts/1.5-hooks-verify.sh` returns PASS
+
+---
+
+## Troubleshooting
+
+### Hooks Not Firing
+
+```bash
+# Check Claude Code version supports hooks
+claude --version
+
+# Verify settings.json is valid JSON
+python3 -c "import json; json.load(open('$HOME/.claude/settings.json'))"
+
+# Check file permissions
+ls -la ~/.claude/hooks/
+```
+
+### "Command not found: python3"
+
+```bash
+# macOS
+brew install python3
+
+# Ubuntu
+sudo apt install python3
+```
+
+### Hook Timeouts
+
+Hooks have a timeout. If KB search is slow:
+
+1. Check DATABASE_URL is set correctly
+2. Verify PostgreSQL is running
+3. Consider increasing timeout in hook scripts
+
+### ReasoningBank Empty
+
+```bash
+# Initialize ReasoningBank
+npx claude-flow memory init
+
+# Or create manually
+mkdir -p .swarm
+sqlite3 .swarm/memory.db "CREATE TABLE IF NOT EXISTS reasoning_memory (id TEXT PRIMARY KEY, title TEXT, content TEXT, namespace TEXT, created_at TEXT);"
+```
+
+---
+
+## Exit Criteria
+
+Hooks are installed, configured, pre-trained, and verified working.
+
+**Proceed to Phase 2: KB Creation**