create-merlin-brain 3.6.3 → 3.7.0

package/files/loop/lib/blend-handoff.sh

@@ -0,0 +1,284 @@
+#!/usr/bin/env bash
+#
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  BLEND ENGINE — Stage 3: Structured Handoffs                              ║
+# ║  Clean JSON pipeline context instead of raw output dumping                ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+#
+# Replace raw text output passing between agents with structured JSON:
+# - decisions_made: what the agent decided and why
+# - files_changed: what files were created/modified/deleted
+# - open_questions: unresolved items for the next agent
+# - key_constraints: constraints the next agent must respect
+# - exit_status: success/partial/failed
+#
+# This gives the next agent clean context instead of 10K of noise.
+#
+# Requires: blend.sh loaded first
+
+# Colors
+: "${RESET:=\033[0m}"
+: "${BOLD:=\033[1m}"
+: "${DIM:=\033[2m}"
+: "${GREEN:=\033[32m}"
+: "${YELLOW:=\033[33m}"
+: "${CYAN:=\033[36m}"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Handoff File Management
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Create an empty handoff structure
+handoff_create() {
+  local session_dir="${1:-/tmp/merlin-blend-$$}"
+  local handoff_file="${session_dir}/handoff.json"
+  mkdir -p "$session_dir"
+
+  cat > "$handoff_file" << 'EMPTY_HANDOFF'
+{
+  "version": 1,
+  "steps": [],
+  "accumulated_context": {
+    "decisions": [],
+    "files_changed": [],
+    "constraints": [],
+    "open_questions": []
+  }
+}
+EMPTY_HANDOFF
+
+  echo "$handoff_file"
+}
+
+# Append a step result to the handoff chain
+# Usage: handoff_append <handoff_file> <step_name> <raw_output>
+handoff_append() {
+  local handoff_file="$1"
+  local step_name="$2"
+  local raw_output="$3"
+
+  if [ ! -f "$handoff_file" ]; then
+    echo -e "${RED}Handoff file not found: $handoff_file${RESET}" >&2
+    return 1
+  fi
+
+  # Extract structured data from raw output using lightweight parsing
+  local decisions files_changed open_questions constraints status
+
+  # Parse decisions (lines starting with "Decision:", "Decided:", or "→")
+  decisions=$(echo "$raw_output" | grep -iE '^\s*(decision|decided|→|⟶):' | head -10 | sed 's/^[^:]*: *//' | python3 -c "
+import sys, json
+lines = [l.strip() for l in sys.stdin if l.strip()]
+print(json.dumps(lines))
+" 2>/dev/null || echo "[]")
+
+  # Parse files changed (lines with file paths)
+  files_changed=$(echo "$raw_output" | grep -oE '(created|modified|deleted|updated|wrote|edited)\s+`?[a-zA-Z0-9_./-]+`?' | head -20 | python3 -c "
+import sys, json, re
+files = []
+for line in sys.stdin:
+    match = re.search(r'(created|modified|deleted|updated|wrote|edited)\s+\`?([a-zA-Z0-9_./-]+)\`?', line.strip())
+    if match:
+        files.append({'action': match.group(1), 'path': match.group(2)})
+print(json.dumps(files))
+" 2>/dev/null || echo "[]")
+
+  # Parse open questions (lines with "?" or "TODO" or "QUESTION")
+  open_questions=$(echo "$raw_output" | grep -iE '(\?|TODO|QUESTION|open question|needs decision)' | head -5 | python3 -c "
+import sys, json
+lines = [l.strip() for l in sys.stdin if l.strip()]
+print(json.dumps(lines))
+" 2>/dev/null || echo "[]")
+
+  # Determine status
+  if echo "$raw_output" | grep -qi "error\|failed\|FAIL"; then
+    status="failed"
+  elif echo "$raw_output" | grep -qi "partial\|incomplete\|skipped"; then
+    status="partial"
+  else
+    status="success"
+  fi
+
+  # Build the step entry and merge into handoff
+  python3 << PYEOF
+import json, sys
+from datetime import datetime, timezone
+
+handoff_file = "$handoff_file"
+step_name = "$step_name"
+status = "$status"
+
+with open(handoff_file, 'r') as f:
+    handoff = json.load(f)
+
+# Parse extracted data
+try:
+    decisions = json.loads('''$decisions''')
+except: decisions = []
+try:
+    files_changed = json.loads('''$files_changed''')
+except: files_changed = []
+try:
+    open_questions = json.loads('''$open_questions''')
+except: open_questions = []
+
+# Build step entry
+step = {
+    "name": step_name,
+    "timestamp": datetime.now(timezone.utc).isoformat(),
+    "status": status,
+    "decisions": decisions,
+    "files_changed": files_changed,
+    "open_questions": open_questions,
+    "output_length": len('''$raw_output''')
+}
+
+handoff["steps"].append(step)
+
+# Accumulate context
+handoff["accumulated_context"]["decisions"].extend(decisions)
+handoff["accumulated_context"]["files_changed"].extend(files_changed)
+handoff["accumulated_context"]["open_questions"] = open_questions  # Only latest
+# Keep constraints from previous steps
+if decisions:
+    handoff["accumulated_context"]["constraints"].extend(
+        [f"Step '{step_name}' decided: {d}" for d in decisions[:3]]
+    )
+
+with open(handoff_file, 'w') as f:
+    json.dump(handoff, f, indent=2)
+
+print(f"Handoff updated: {step_name} ({status})")
+PYEOF
+}
+
+# Format handoff context for injection into next agent's prompt
+# Returns a clean, readable summary (not raw JSON)
+handoff_format_for_agent() {
+  local handoff_file="$1"
+
+  if [ ! -f "$handoff_file" ]; then
+    echo ""
+    return
+  fi
+
+  python3 << PYEOF
+import json
+
+with open("$handoff_file", 'r') as f:
+    handoff = json.load(f)
+
+ctx = handoff.get("accumulated_context", {})
+steps = handoff.get("steps", [])
+
+if not steps:
+    print("")
+    exit()
+
+output = "## Pipeline Context (from previous steps)\n\n"
+
+# Steps summary
+output += "### Completed Steps\n"
+for s in steps:
+    icon = "✓" if s["status"] == "success" else "⚠" if s["status"] == "partial" else "✗"
+    output += f"- {icon} **{s['name']}** ({s['status']})\n"
+output += "\n"
+
+# Key decisions
+decisions = ctx.get("decisions", [])
+if decisions:
+    output += "### Decisions Made (DO NOT contradict these)\n"
+    for d in decisions[-10:]:  # Last 10
+        output += f"- {d}\n"
+    output += "\n"
+
+# Files already changed
+files = ctx.get("files_changed", [])
+if files:
+    output += "### Files Already Changed (check before modifying)\n"
+    for f in files[-20:]:  # Last 20
+        if isinstance(f, dict):
+            output += f"- {f.get('action', '?')}: \`{f.get('path', '?')}\`\n"
+        else:
+            output += f"- {f}\n"
+    output += "\n"
+
+# Constraints
+constraints = ctx.get("constraints", [])
+if constraints:
+    output += "### Constraints (MUST respect)\n"
+    for c in constraints[-5:]:
+        output += f"- {c}\n"
+    output += "\n"
+
+# Open questions
+questions = ctx.get("open_questions", [])
+if questions:
+    output += "### Open Questions (resolve if relevant to your task)\n"
+    for q in questions:
+        output += f"- {q}\n"
+    output += "\n"
+
+print(output)
+PYEOF
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Pipeline: Execute a sequence of blended agents with structured handoffs
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Execute a multi-step pipeline with clean handoffs between agents
+# Usage: blend_pipeline <session_dir> "step1_task" "step2_task" ...
+blend_pipeline() {
+  local session_dir="$1"
+  shift
+  local tasks=("$@")
+
+  mkdir -p "$session_dir"
+
+  # Create handoff chain
+  local handoff_file
+  handoff_file=$(handoff_create "$session_dir")
+
+  local step_count=${#tasks[@]}
+  echo -e "${MAGENTA}${BOLD}  Pipeline: $step_count steps${RESET}" >&2
+
+  local final_output=""
+
+  for i in "${!tasks[@]}"; do
+    local task="${tasks[$i]}"
+    local step_num=$((i + 1))
+    local step_name="step-${step_num}"
+
+    echo -e "${CYAN}  [${step_num}/${step_count}]${RESET} ${task:0:60}..." >&2
+
+    # Get accumulated context from previous steps
+    local pipeline_context
+    pipeline_context=$(handoff_format_for_agent "$handoff_file")
+
+    # Combine pipeline context with current task
+    local full_context=""
+    if [ -n "$pipeline_context" ]; then
+      full_context="$pipeline_context"
+    fi
+
+    # Execute with blend
+    local step_output
+    step_output=$(blend_and_spawn "$task" "$full_context" "${session_dir}/${step_name}")
+    local step_exit=$?
+
+    # Record in handoff
+    handoff_append "$handoff_file" "$step_name" "$step_output"
+
+    if [ $step_exit -ne 0 ]; then
+      echo -e "${RED}  ✗ Step $step_num failed${RESET}" >&2
+      final_output="$step_output"
+      break
+    fi
+
+    echo -e "${GREEN}  ✓ Step $step_num complete${RESET}" >&2
+    final_output="$step_output"
+  done
+
+  echo "$final_output"
+}

package/files/loop/lib/blend-learn.sh

@@ -0,0 +1,337 @@
+#!/usr/bin/env bash
+#
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  BLEND ENGINE — Stage 4: Blend Learning                                  ║
+# ║  Track which blend combinations succeed, adjust scoring over time        ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+#
+# Every blend execution produces a signal: did it work?
+# This module captures those signals and uses them to boost or penalize
+# agent combinations in future scoring.
+#
+# Data storage:
+#   Global:  ~/.merlin/blend-learn.jsonl (universal patterns)
+#   Project: .merlin-loop/blend-learn.jsonl (project-specific patterns)
+#
+# Signal types:
+#   - exit_code: 0 = success, non-zero = failure
+#   - verification_verdict: PASS / PASS_WITH_WARNINGS / FAIL (from blend-verify.sh)
+#   - duration: how long the spawn took (fast = good signal)
+#   - agent_combo: which agents were blended
+#
+# Scoring integration:
+#   After blend_score_all() runs keyword matching, learning applies a
+#   multiplier per agent based on historical success rate:
+#     success_rate > 0.8 → +2 bonus
+#     success_rate > 0.6 → +1 bonus
+#     success_rate < 0.3 → -1 penalty
+#     success_rate < 0.1 → -2 penalty
+#   Minimum 5 samples required before adjustments kick in.
+#
+# Requires: blend.sh loaded first
+
+# Colors
+: "${RESET:=\033[0m}"
+: "${BOLD:=\033[1m}"
+: "${DIM:=\033[2m}"
+: "${GREEN:=\033[32m}"
+: "${YELLOW:=\033[33m}"
+: "${RED:=\033[31m}"
+: "${CYAN:=\033[36m}"
+: "${MAGENTA:=\033[35m}"
+
+# Storage paths
+LEARN_GLOBAL_FILE="${HOME}/.merlin/blend-learn.jsonl"
+LEARN_PROJECT_FILE="${MERLIN_LOOP_DIR:-.merlin-loop}/blend-learn.jsonl"
+
+# Minimum samples before learning kicks in
+LEARN_MIN_SAMPLES="${LEARN_MIN_SAMPLES:-5}"
+
+# How many recent records to consider (sliding window)
+LEARN_WINDOW="${LEARN_WINDOW:-100}"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Recording: Capture outcome signals after every blend execution
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Record a blend execution outcome
+# Usage: learn_record <primary_agent> <secondary_agents_csv> <exit_code> <duration_secs> [verdict]
+learn_record() {
+  local primary="$1"
+  local secondaries="${2:-}"
+  local exit_code="${3:-0}"
+  local duration="${4:-0}"
+  local verdict="${5:-}"  # From verification: PASS/PASS_WITH_WARNINGS/FAIL
+
+  # Ensure directories exist
+  mkdir -p "$(dirname "$LEARN_GLOBAL_FILE")"
+  mkdir -p "$(dirname "$LEARN_PROJECT_FILE")"
+
+  # Determine success
+  local success="true"
+  if [ "$exit_code" -ne 0 ]; then
+    success="false"
+  fi
+  if [ "$verdict" = "FAIL" ]; then
+    success="false"
+  fi
+
+  # Build the record
+  local record
+  record=$(python3 -c "
+import json
+from datetime import datetime, timezone
+
+record = {
+    'timestamp': datetime.now(timezone.utc).isoformat(),
+    'primary': '$primary',
+    'secondaries': '$secondaries'.split(',') if '$secondaries' else [],
+    'exit_code': $exit_code,
+    'duration_secs': $duration,
+    'verdict': '$verdict' or None,
+    'success': $success,
+    'project': '$(basename "$(pwd)")'
+}
+print(json.dumps(record))
+" 2>/dev/null)
+
+  if [ -z "$record" ]; then
+    return 1
+  fi
+
+  # Append to both files
+  echo "$record" >> "$LEARN_GLOBAL_FILE"
+  echo "$record" >> "$LEARN_PROJECT_FILE"
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Analysis: Compute success rates per agent
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Get the score adjustment for an agent based on learning history
+# Returns: integer adjustment (-2, -1, 0, +1, +2)
+learn_get_boost() {
+  local agent_key="$1"
+
+  # Check project-specific first (more relevant), then global
+  local boost=0
+  for learn_file in "$LEARN_PROJECT_FILE" "$LEARN_GLOBAL_FILE"; do
+    [ ! -f "$learn_file" ] && continue
+
+    local result
+    result=$(python3 << PYEOF 2>/dev/null
+import json, sys
+
+agent_key = "$agent_key"
+window = $LEARN_WINDOW
+min_samples = $LEARN_MIN_SAMPLES
+
+records = []
+try:
+    with open("$learn_file", 'r') as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    records.append(json.loads(line))
+                except:
+                    pass
+except:
+    pass
+
+# Filter to recent window, matching this agent as primary or secondary
+relevant = []
+for r in records[-window:]:
+    if r.get('primary') == agent_key:
+        relevant.append(r)
+    elif agent_key in r.get('secondaries', []):
+        relevant.append(r)
+
+total = len(relevant)
+if total < min_samples:
+    print(0)
+    sys.exit()
+
+successes = sum(1 for r in relevant if r.get('success'))
+rate = successes / total
+
+if rate > 0.8:
+    print(2)
+elif rate > 0.6:
+    print(1)
+elif rate < 0.1:
+    print(-2)
+elif rate < 0.3:
+    print(-1)
+else:
+    print(0)
+PYEOF
+)
+    if [ -n "$result" ] && [ "$result" != "0" ]; then
+      boost="$result"
+      break  # Project-specific takes priority
+    fi
+  done
+
+  echo "$boost"
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Scoring Integration: Apply learning boosts to scored agents
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Take scored agents (from blend_score_all) and apply learning adjustments
+# Input: stdin of "score:key:label:file" lines
+# Output: adjusted "score:key:label:file" lines, re-sorted
+learn_apply_weights() {
+  # Check if any learning data exists
+  if [ ! -f "$LEARN_PROJECT_FILE" ] && [ ! -f "$LEARN_GLOBAL_FILE" ]; then
+    cat  # Pass through unchanged
+    return
+  fi
+
+  local lines=()
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    lines+=("$line")
+  done
+
+  # Apply boosts
+  local adjusted=()
+  for line in "${lines[@]}"; do
+    local score key label file
+    IFS=: read -r score key label file <<< "$line"
+    [ -z "$key" ] && continue
+
+    local boost
+    boost=$(learn_get_boost "$key")
+
+    if [ "$boost" != "0" ]; then
+      local new_score=$((score + boost))
+      # Floor at 0
+      [ "$new_score" -lt 0 ] && new_score=0
+      adjusted+=("${new_score}:${key}:${label}:${file}")
+    else
+      adjusted+=("$line")
+    fi
+  done
+
+  # Re-sort by score descending
+  printf '%s\n' "${adjusted[@]}" | sort -t: -k1 -nr
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Statistics: Show learning insights
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Show learning statistics
+learn_stats() {
+  local learn_file="${1:-$LEARN_PROJECT_FILE}"
+
+  if [ ! -f "$learn_file" ]; then
+    echo -e "${DIM}  No learning data yet.${RESET}" >&2
+    return
+  fi
+
+  python3 << PYEOF
+import json
+from collections import defaultdict
+
+records = []
+with open("$learn_file", 'r') as f:
+    for line in f:
+        line = line.strip()
+        if line:
+            try:
+                records.append(json.loads(line))
+            except:
+                pass
+
+if not records:
+    print("  No learning data.")
+    exit()
+
+# Aggregate by primary agent
+stats = defaultdict(lambda: {'total': 0, 'success': 0, 'avg_duration': 0, 'durations': []})
+
+for r in records:
+    key = r.get('primary', 'unknown')
+    stats[key]['total'] += 1
+    if r.get('success'):
+        stats[key]['success'] += 1
+    dur = r.get('duration_secs', 0)
+    if dur > 0:
+        stats[key]['durations'].append(dur)
+
+print(f"\n  📊 Blend Learning Stats ({len(records)} total executions)\n")
+print(f"  {'Agent':<20} {'Success':>8} {'Total':>6} {'Rate':>7} {'Avg Time':>10}")
+print(f"  {'─'*20} {'─'*8} {'─'*6} {'─'*7} {'─'*10}")
+
+for key in sorted(stats.keys(), key=lambda k: stats[k]['total'], reverse=True):
+    s = stats[key]
+    rate = s['success'] / s['total'] if s['total'] > 0 else 0
+    avg_dur = sum(s['durations']) / len(s['durations']) if s['durations'] else 0
+
+    # Color coding
+    if rate > 0.8:
+        indicator = "✓"
+    elif rate < 0.3:
+        indicator = "✗"
+    else:
+        indicator = "○"
+
+    dur_str = f"{avg_dur:.0f}s" if avg_dur > 0 else "—"
+    print(f"  {indicator} {key:<18} {s['success']:>8} {s['total']:>6} {rate:>6.0%} {dur_str:>10}")
+
+# Top combos
+combos = defaultdict(lambda: {'total': 0, 'success': 0})
+for r in records:
+    combo_key = r.get('primary', '?') + '+' + ','.join(sorted(r.get('secondaries', [])))
+    combos[combo_key]['total'] += 1
+    if r.get('success'):
+        combos[combo_key]['success'] += 1
+
+if combos:
+    print(f"\n  🔗 Top Blend Combinations:")
+    for combo in sorted(combos.keys(), key=lambda k: combos[k]['total'], reverse=True)[:5]:
+        c = combos[combo]
+        rate = c['success'] / c['total']
+        print(f"    {combo:<40} {c['success']}/{c['total']} ({rate:.0%})")
+PYEOF
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Maintenance: Reset and cleanup
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Reset project learning data
+learn_reset_project() {
+  rm -f "$LEARN_PROJECT_FILE"
+  echo -e "${YELLOW}  Project learning data reset.${RESET}" >&2
+}
+
+# Reset all learning data
+learn_reset_all() {
+  rm -f "$LEARN_PROJECT_FILE"
+  rm -f "$LEARN_GLOBAL_FILE"
+  echo -e "${YELLOW}  All learning data reset.${RESET}" >&2
+}
+
+# Compact learning data (keep only last N records)
+learn_compact() {
+  local max_records="${1:-500}"
+
+  for learn_file in "$LEARN_PROJECT_FILE" "$LEARN_GLOBAL_FILE"; do
+    [ ! -f "$learn_file" ] && continue
+
+    local count
+    count=$(wc -l < "$learn_file" 2>/dev/null || echo "0")
+
+    if [ "$count" -gt "$max_records" ]; then
+      local tmp_file="${learn_file}.tmp"
+      tail -n "$max_records" "$learn_file" > "$tmp_file"
+      mv "$tmp_file" "$learn_file"
+      echo -e "${DIM}  Compacted $learn_file: $count → $max_records records${RESET}" >&2
+    fi
+  done
+}