jfl 0.5.0 → 0.6.1

package/scripts/train/v2/transform_buffer.py

@@ -0,0 +1,227 @@
+"""
+Transform v1 training buffer (state, action, reward) to v2 format (current_state, goal, correct_tool).
+
+Reads .jfl/training-buffer.jsonl and .jfl/agents/*.toml to produce v2 training data
+with 70/15/15 train/val/test splits.
+"""
+
+import json
+import os
+import sys
+import random
+import argparse
+from pathlib import Path
+
+ACTION_TYPE_MAP = {
+    "fix": "fix_bug",
+    "refactor": "refactor_code",
+    "feature": "add_feature",
+    "test": "add_tests",
+    "config": "update_config",
+    "experiment": "run_experiment",
+}
+
+def load_domain(domain_path: str) -> dict:
+    with open(domain_path) as f:
+        return json.load(f)
+
+def load_agent_goals(agents_dir: str) -> dict[str, str]:
+    goals = {}
+    agents_path = Path(agents_dir)
+    if not agents_path.exists():
+        return goals
+
+    for toml_file in agents_path.glob("*.toml"):
+        name = None
+        metric = None
+        direction = None
+        scope = None
+
+        for line in toml_file.read_text().splitlines():
+            line = line.strip()
+            if line.startswith("name"):
+                name = line.split("=", 1)[1].strip().strip('"')
+            elif line.startswith("metric"):
+                metric = line.split("=", 1)[1].strip().strip('"')
+            elif line.startswith("direction"):
+                direction = line.split("=", 1)[1].strip().strip('"')
+            elif line.startswith("scope") and "=" in line and not line.startswith("scope_files"):
+                scope = line.split("=", 1)[1].strip().strip('"')
+
+        if name and metric and direction:
+            verb = "Improve" if direction == "maximize" else "Reduce"
+            scope_str = f" for {scope}" if scope else ""
+            goals[name] = f"{verb} {metric.replace('_', ' ')}{scope_str}"
+
+    return goals
+
+def format_state_text(state: dict) -> str:
+    dims = state.get("dimension_scores", {})
+    dims_str = ", ".join(f"{k}={v:.4f}" for k, v in dims.items()) if dims else "none"
+    deltas = state.get("recent_deltas", [])
+    deltas_str = ", ".join(f"{'+' if d >= 0 else ''}{d:.4f}" for d in deltas) if deltas else "none"
+    return "\n".join([
+        f"Agent: {state.get('agent', 'unknown')}",
+        f"Composite: {state.get('composite_score', 0):.4f}",
+        f"Tests: {state.get('tests_passing', 0)}/{state.get('tests_total', 0)}",
+        f"Trajectory: {state.get('trajectory_length', 0)}",
+        f"Dimensions: {dims_str}",
+        f"Recent deltas: {deltas_str}",
+    ])
+
+def map_action_type(action_type: str) -> str | None:
+    return ACTION_TYPE_MAP.get(action_type)
+
+def transform_entry(entry: dict, agent_goals: dict, valid_tools: set) -> dict | None:
+    state = entry.get("state", {})
+    action = entry.get("action", {})
+    reward = entry.get("reward", {})
+
+    action_type = action.get("type", "")
+    tool_name = map_action_type(action_type)
+    if not tool_name or tool_name not in valid_tools:
+        return None
+
+    agent_name = entry.get("agent", state.get("agent", ""))
+    goal = agent_goals.get(agent_name)
+    if not goal:
+        metric_hint = action.get("description", "")[:80]
+        goal = f"Improve codebase quality: {metric_hint}" if metric_hint else "Improve overall codebase quality"
+
+    current_state = format_state_text(state)
+
+    return {
+        "current_state": current_state,
+        "goal": goal,
+        "correct_tool": tool_name,
+        "source": "buffer",
+        "agent": agent_name,
+        "improved": reward.get("improved", False),
+        "reward_delta": reward.get("composite_delta", 0),
+    }
+
+def transform_buffer(
+    buffer_path: str,
+    agents_dir: str,
+    domain_path: str,
+    output_dir: str,
+    improved_only: bool = True,
+    seed: int = 42,
+) -> dict:
+    domain = load_domain(domain_path)
+    valid_tools = {t["name"] for t in domain["tools"]}
+    agent_goals = load_agent_goals(agents_dir)
+
+    entries = []
+    with open(buffer_path) as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entries.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+
+    print(f"Loaded {len(entries)} raw training buffer entries")
+    if agent_goals:
+        print(f"Agent goals: {json.dumps(agent_goals, indent=2)}")
+
+    examples = []
+    skipped_type = 0
+    skipped_improved = 0
+
+    for entry in entries:
+        transformed = transform_entry(entry, agent_goals, valid_tools)
+        if transformed is None:
+            skipped_type += 1
+            continue
+
+        if improved_only and not transformed["improved"]:
+            skipped_improved += 1
+            continue
+
+        examples.append({
+            "current_state": transformed["current_state"],
+            "goal": transformed["goal"],
+            "correct_tool": transformed["correct_tool"],
+            "source": transformed["source"],
+        })
+
+    print(f"Transformed: {len(examples)} examples")
+    print(f"Skipped: {skipped_type} (unmapped type), {skipped_improved} (not improved)")
+
+    if not examples:
+        print("No examples to write. Check action types and improved filter.")
+        return {"train": 0, "val": 0, "test": 0}
+
+    random.seed(seed)
+    random.shuffle(examples)
+
+    n = len(examples)
+    train_end = int(n * 0.7)
+    val_end = int(n * 0.85)
+
+    splits = {
+        "train": examples[:train_end],
+        "val": examples[train_end:val_end],
+        "test": examples[val_end:],
+    }
+
+    os.makedirs(output_dir, exist_ok=True)
+
+    counts = {}
+    for split_name, split_data in splits.items():
+        path = os.path.join(output_dir, f"{split_name}.jsonl")
+        with open(path, "w") as f:
+            for ex in split_data:
+                f.write(json.dumps(ex) + "\n")
+        counts[split_name] = len(split_data)
+        print(f"  {split_name}: {len(split_data)} examples -> {path}")
+
+    # Class balance report
+    from collections import Counter
+    tool_counts = Counter(ex["correct_tool"] for ex in examples)
+    print(f"\nClass distribution:")
+    for tool, count in tool_counts.most_common():
+        pct = count / len(examples) * 100
+        print(f"  {tool:25s} {count:4d} ({pct:5.1f}%)")
+
+    return counts
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Transform v1 training buffer to v2 format")
+    parser.add_argument("--buffer", default=".jfl/training-buffer.jsonl", help="Path to training buffer JSONL")
+    parser.add_argument("--agents", default=".jfl/agents", help="Path to agents directory")
+    parser.add_argument("--domain", default=None, help="Path to domain.json")
+    parser.add_argument("--output", default=".jfl/v2-data", help="Output directory for split data")
+    parser.add_argument("--all", action="store_true", help="Include entries where improved=false")
+    parser.add_argument("--seed", type=int, default=42, help="Random seed for split")
+    args = parser.parse_args()
+
+    # Default domain path: relative to this script
+    domain_path = args.domain
+    if domain_path is None:
+        domain_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "domain.json")
+
+    if not os.path.exists(args.buffer):
+        print(f"Training buffer not found: {args.buffer}")
+        sys.exit(1)
+
+    if not os.path.exists(domain_path):
+        print(f"Domain file not found: {domain_path}")
+        sys.exit(1)
+
+    transform_buffer(
+        buffer_path=args.buffer,
+        agents_dir=args.agents,
+        domain_path=domain_path,
+        output_dir=args.output,
+        improved_only=not args.all,
+        seed=args.seed,
+    )
+
+
+if __name__ == "__main__":
+    main()

package/scripts/train/v2/validate_data.py

@@ -0,0 +1,115 @@
+"""
+Validate v2 training data quality before training.
+Checks class balance, duplicates, empty fields, and text lengths.
+"""
+
+import json
+import sys
+import os
+import argparse
+from collections import Counter
+
+def validate_dataset(path: str) -> dict:
+    examples = []
+    with open(path) as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            examples.append(json.loads(line))
+
+    results = {"total": len(examples), "issues": []}
+
+    print(f"Total examples: {len(examples)}")
+
+    tool_counts = Counter(ex["correct_tool"] for ex in examples)
+    print("\nClass distribution:")
+    for tool, count in tool_counts.most_common():
+        pct = count / len(examples) * 100
+        bar = "█" * int(pct)
+        print(f"  {tool:30s} {count:4d} ({pct:5.1f}%) {bar}")
+
+    max_count = max(tool_counts.values()) if tool_counts else 0
+    min_count = min(tool_counts.values()) if tool_counts else 0
+    ratio = max_count / min_count if min_count > 0 else float("inf")
+    if ratio > 3.0:
+        msg = f"Class imbalance: {ratio:.1f}x ratio (max/min)"
+        print(f"\n  ⚠️  {msg}")
+        results["issues"].append(msg)
+    else:
+        print(f"\n  ✅ Class balance OK: {ratio:.1f}x ratio")
+
+    results["class_ratio"] = ratio
+    results["tool_counts"] = dict(tool_counts)
+
+    goal_set = set()
+    dupes = 0
+    for ex in examples:
+        key = (ex["goal"], ex["correct_tool"])
+        if key in goal_set:
+            dupes += 1
+        goal_set.add(key)
+    if dupes > 0:
+        msg = f"{dupes} duplicate (goal, tool) pairs"
+        print(f"\n  ⚠️  {msg}")
+        results["issues"].append(msg)
+    else:
+        print("\n  ✅ No duplicate (goal, tool) pairs")
+    results["duplicates"] = dupes
+
+    empty_states = sum(1 for ex in examples if not ex.get("current_state", "").strip())
+    empty_goals = sum(1 for ex in examples if not ex.get("goal", "").strip())
+    if empty_states or empty_goals:
+        msg = f"Empty fields: {empty_states} states, {empty_goals} goals"
+        print(f"\n  ⚠️  {msg}")
+        results["issues"].append(msg)
+    else:
+        print("  ✅ No empty fields")
+
+    if examples:
+        avg_state_len = sum(len(ex.get("current_state", "")) for ex in examples) / len(examples)
+        avg_goal_len = sum(len(ex.get("goal", "")) for ex in examples) / len(examples)
+        print(f"\n  Avg state length: {avg_state_len:.0f} chars")
+        print(f"  Avg goal length:  {avg_goal_len:.0f} chars")
+        results["avg_state_len"] = avg_state_len
+        results["avg_goal_len"] = avg_goal_len
+
+    return results
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Validate v2 training data quality")
+    parser.add_argument("--data-dir", default=".jfl/v2-data", help="Directory with train/val/test JSONL files")
+    parser.add_argument("--json", action="store_true", help="Output results as JSON")
+    args = parser.parse_args()
+
+    all_results = {}
+    has_issues = False
+
+    for split in ["train", "val", "test"]:
+        path = os.path.join(args.data_dir, f"{split}.jsonl")
+        if not os.path.exists(path):
+            print(f"\nSkipping {split} (not found)")
+            continue
+
+        print(f"\n{'=' * 60}")
+        print(f"  {split.upper()} SPLIT")
+        print(f"{'=' * 60}")
+
+        results = validate_dataset(path)
+        all_results[split] = results
+        if results["issues"]:
+            has_issues = True
+
+    if args.json:
+        print(json.dumps(all_results, indent=2))
+
+    if has_issues:
+        print(f"\n⚠️  Issues found. Review above warnings.")
+        sys.exit(1)
+    else:
+        print(f"\n✅ All validation checks passed.")
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/settings.json

@@ -6,12 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "./scripts/session/session-init.sh"
-          },
-          {
-            "type": "command",
-            "command": "jfl context-hub ensure >> .jfl/logs/context-hub.log 2>&1 &",
-            "async": true
+            "command": "./scripts/session/session-start-hub.sh || ./scripts/session/session-init.sh"
           }
         ]
       }
@@ -73,15 +68,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "BRANCH=$(cat .jfl/current-session-branch.txt 2>/dev/null || git branch --show-current); JOURNAL=\".jfl/journal/${BRANCH}.jsonl\"; if [ ! -s \"$JOURNAL\" ] 2>/dev/null; then echo '⚠️  No journal entry for session'; else echo '✓ Journal exists'; fi; exit 0"
-          },
-          {
-            "type": "command",
-            "command": "jfl context-hub stop >> .jfl/logs/context-hub.log 2>&1; echo '✓ Context hub stopped'; exit 0"
-          },
-          {
-            "type": "command",
-            "command": "./scripts/session/session-cleanup.sh >> .jfl/logs/session-cleanup.log 2>&1 || echo 'Cleanup skipped'; exit 0"
+            "command": "./scripts/session/session-end-hub.sh || exit 0"
           }
         ]
       }

package/template/scripts/session/session-cleanup.sh

@@ -48,17 +48,8 @@ if [ -f ".auto-merge.pid" ]; then
   rm -f ".auto-merge.pid"
 fi
 
-# Stop context-hub if running (already handled by Stop hook, but be defensive)
-if [ -f ".jfl/context-hub.pid" ]; then
-  PID=$(cat ".jfl/context-hub.pid")
-  if kill -0 "$PID" 2>/dev/null; then
-    echo "  Stopping context-hub (PID: $PID)..."
-    kill -TERM "$PID" 2>/dev/null || true
-    sleep 1
-    kill -0 "$PID" 2>/dev/null && kill -9 "$PID" 2>/dev/null || true
-  fi
-  rm -f ".jfl/context-hub.pid"
-fi
+# Context Hub is a persistent daemon — do NOT kill it on session end.
+# It serves multiple sessions and runtimes (Claude Code, Pi, etc).
 
 # Get current session info
 BRANCH=$(git branch --show-current 2>/dev/null || echo "")

package/template/scripts/session/session-end-hub.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+#
+# session-end-hub.sh — Session end via Context Hub API
+#
+# Calls POST /api/session/end for journal check + cleanup.
+# Falls back to session-cleanup.sh if hub is unavailable.
+#
+# @purpose Hub-first session cleanup with script fallback
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="${JFL_REPO_DIR:-$(pwd)}"
+RUNTIME="${1:-claude-code}"
+
+cd "$REPO_DIR" || exit 0
+
+# Read port and token
+PORT=$(jq -r '.contextHub.port // empty' .jfl/config.json 2>/dev/null)
+if [ -z "$PORT" ]; then
+  PORT=$(cat .jfl/context-hub.port 2>/dev/null)
+fi
+if [ -z "$PORT" ]; then
+  PORT="4242"
+fi
+
+TOKEN=$(cat .jfl/context-hub.token 2>/dev/null || echo "")
+AUTH_HEADER=""
+if [ -n "$TOKEN" ]; then
+  AUTH_HEADER="Authorization: Bearer $TOKEN"
+fi
+
+HUB_URL="http://localhost:${PORT}"
+RESULT=""
+
+if curl -sf "$HUB_URL/health" >/dev/null 2>&1; then
+  RESULT=$(curl -sf -X POST "$HUB_URL/api/session/end" \
+    -H "Content-Type: application/json" \
+    ${AUTH_HEADER:+-H "$AUTH_HEADER"} \
+    -d "{\"runtime\":\"$RUNTIME\"}" \
+    --max-time 90 2>/dev/null) || RESULT=""
+fi
+
+if [ -n "$RESULT" ]; then
+  HAS_JOURNAL=$(echo "$RESULT" | jq -r '.hasJournal // false' 2>/dev/null)
+  CLEANUP=$(echo "$RESULT" | jq -r '.cleanupResult // "unknown"' 2>/dev/null)
+
+  if [ "$HAS_JOURNAL" = "true" ]; then
+    echo '✓ Journal exists'
+  else
+    echo '⚠️  No journal entry for session'
+  fi
+
+  if [ "$CLEANUP" = "ok" ]; then
+    echo '✓ Session cleanup complete'
+  else
+    echo "Cleanup: $CLEANUP"
+  fi
+else
+  # Fallback: run cleanup script directly
+  BRANCH=$(cat .jfl/current-session-branch.txt 2>/dev/null || git branch --show-current 2>/dev/null)
+  JOURNAL=".jfl/journal/${BRANCH}.jsonl"
+  if [ ! -s "$JOURNAL" ] 2>/dev/null; then
+    echo '⚠️  No journal entry for session'
+  else
+    echo '✓ Journal exists'
+  fi
+
+  if [ -x "$SCRIPT_DIR/session-cleanup.sh" ]; then
+    "$SCRIPT_DIR/session-cleanup.sh" >> .jfl/logs/session-cleanup.log 2>&1 || echo 'Cleanup skipped'
+  fi
+fi
+
+exit 0

package/template/scripts/session/session-start-hub.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+#
+# session-start-hub.sh — Session init via Context Hub API
+#
+# Ensures hub is running, then calls POST /api/session/init.
+# Falls back to session-init.sh if hub is unavailable.
+#
+# @purpose Hub-first session initialization with script fallback
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="${JFL_REPO_DIR:-$(pwd)}"
+RUNTIME="${1:-claude-code}"
+
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+cd "$REPO_DIR" || exit 1
+
+# Ensure .jfl directories exist before any logging
+mkdir -p .jfl/logs .jfl/journal
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  JFL Session Init"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Step 1: Ensure Context Hub is running
+jfl context-hub ensure >> .jfl/logs/context-hub.log 2>&1 || true
+
+# Step 2: Read port and token
+PORT=$(jq -r '.contextHub.port // empty' .jfl/config.json 2>/dev/null)
+if [ -z "$PORT" ]; then
+  # Try runtime port file
+  PORT=$(cat .jfl/context-hub.port 2>/dev/null)
+fi
+if [ -z "$PORT" ]; then
+  PORT="4242"
+fi
+
+TOKEN=$(cat .jfl/context-hub.token 2>/dev/null || echo "")
+AUTH_HEADER=""
+if [ -n "$TOKEN" ]; then
+  AUTH_HEADER="Authorization: Bearer $TOKEN"
+fi
+
+# Step 3: Call Hub API
+HUB_URL="http://localhost:${PORT}"
+RESULT=""
+
+if curl -sf "$HUB_URL/health" >/dev/null 2>&1; then
+  RESULT=$(curl -sf -X POST "$HUB_URL/api/session/init" \
+    -H "Content-Type: application/json" \
+    ${AUTH_HEADER:+-H "$AUTH_HEADER"} \
+    -d "{\"runtime\":\"$RUNTIME\"}" \
+    --max-time 90 2>/dev/null) || RESULT=""
+fi
+
+if [ -n "$RESULT" ]; then
+  # Parse Hub response
+  BRANCH=$(echo "$RESULT" | jq -r '.branch // "unknown"' 2>/dev/null)
+  SYNC_OK=$(echo "$RESULT" | jq -r '.syncOk // false' 2>/dev/null)
+  DOC_ERRORS=$(echo "$RESULT" | jq -r '.doctor.errors // 0' 2>/dev/null)
+  DOC_WARNINGS=$(echo "$RESULT" | jq -r '.doctor.warnings // 0' 2>/dev/null)
+  WARNINGS=$(echo "$RESULT" | jq -r '.warnings[]?' 2>/dev/null)
+
+  if [ "$SYNC_OK" = "true" ]; then
+    echo -e "${GREEN}✓${NC}  Repos synced"
+  else
+    echo -e "${YELLOW}⚠${NC}  Sync had warnings"
+  fi
+
+  if [ "$DOC_ERRORS" -gt 0 ] 2>/dev/null; then
+    echo -e "${YELLOW}⚠${NC}  Doctor: $DOC_ERRORS errors, $DOC_WARNINGS warnings"
+  elif [ "$DOC_WARNINGS" -gt 0 ] 2>/dev/null; then
+    echo -e "${GREEN}✓${NC}  Doctor: $DOC_WARNINGS warnings"
+  fi
+
+  if [ -n "$WARNINGS" ]; then
+    echo "$WARNINGS" | while IFS= read -r w; do
+      echo -e "${YELLOW}⚠${NC}  $w"
+    done
+  fi
+
+  echo -e "${GREEN}✓${NC}  Session branch: $BRANCH"
+
+  # Start auto-commit daemon (Hub doesn't do this — needs a local detached process)
+  if [ -x "$SCRIPT_DIR/auto-commit.sh" ]; then
+    "$SCRIPT_DIR/auto-commit.sh" start >> .jfl/logs/auto-commit.log 2>&1 &
+    echo -e "${GREEN}✓${NC}  Auto-commit started"
+  fi
+
+  echo -e "${GREEN}✓${NC}  Session ready (via Hub)"
+  echo ""
+else
+  # Fallback: run session-init.sh directly
+  echo -e "${YELLOW}→${NC}  Hub unavailable, falling back to local init"
+  if [ -x "$SCRIPT_DIR/session-init.sh" ]; then
+    "$SCRIPT_DIR/session-init.sh"
+  else
+    echo -e "${YELLOW}⚠${NC}  No session-init.sh found"
+  fi
+fi