create-merlin-brain 2.3.3 → 2.4.0

package/files/loop/lib/modes.sh

@@ -0,0 +1,294 @@
+#!/usr/bin/env bash
+#
+# Merlin Loop - Mode Management
+# Handles automated, interactive, and hybrid loop modes
+#
+
+# Load discussion mode if available
+if [ -f "$SCRIPT_DIR/lib/discuss.sh" ]; then
+  source "$SCRIPT_DIR/lib/discuss.sh"
+fi
+
+# Load timeout if available
+if [ -f "$SCRIPT_DIR/lib/timeout.sh" ]; then
+  source "$SCRIPT_DIR/lib/timeout.sh"
+fi
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Mode Constants
+# ═══════════════════════════════════════════════════════════════════════════════
+
+MODE_AUTO="auto"
+MODE_INTERACTIVE="interactive"
+MODE_HYBRID="hybrid"
+
+# Default mode
+LOOP_MODE="${LOOP_MODE:-$MODE_HYBRID}"
+
+# Hybrid mode settings
+PAUSE_INTERVAL="${MERLIN_PAUSE_INTERVAL:-5}"  # Pause every N tasks in hybrid mode
+
+# Pause reason tracking
+LAST_PAUSE_REASON=""
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Pause Detection
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Check if we should pause based on mode and signals
+# Args: $1 = output from Claude, $2 = current task count
+# Returns: 0 if should pause, 1 if should continue
+should_pause() {
+  local output="$1"
+  local task_count="${2:-0}"
+
+  case "$LOOP_MODE" in
+    "$MODE_AUTO")
+      # Auto mode: only pause on explicit CHECKPOINT_SIGNAL
+      if echo "$output" | grep -q "CHECKPOINT_SIGNAL"; then
+        LAST_PAUSE_REASON="checkpoint"
+        return 0
+      fi
+      return 1
+      ;;
+
+    "$MODE_INTERACTIVE")
+      # Interactive mode: always pause after every task
+      LAST_PAUSE_REASON="interactive"
+      return 0
+      ;;
+
+    "$MODE_HYBRID")
+      # Hybrid mode: pause on decisions, low confidence, checkpoints, or every N tasks
+
+      # Check for decision needed
+      if echo "$output" | grep -q "DECISION_NEEDED"; then
+        LAST_PAUSE_REASON="decision"
+        return 0
+      fi
+
+      # Check for low confidence
+      if echo "$output" | grep -q "LOW_CONFIDENCE"; then
+        LAST_PAUSE_REASON="low_confidence"
+        return 0
+      fi
+
+      # Check for explicit checkpoint
+      if echo "$output" | grep -q "CHECKPOINT_SIGNAL"; then
+        LAST_PAUSE_REASON="checkpoint"
+        return 0
+      fi
+
+      # Check for periodic pause (every N tasks)
+      if [ "$PAUSE_INTERVAL" -gt 0 ] && [ "$task_count" -gt 0 ]; then
+        if [ $((task_count % PAUSE_INTERVAL)) -eq 0 ]; then
+          LAST_PAUSE_REASON="periodic"
+          return 0
+        fi
+      fi
+
+      return 1
+      ;;
+
+    *)
+      # Unknown mode, default to continue
+      return 1
+      ;;
+  esac
+}
+
+# Get human-readable pause reason
+get_pause_reason() {
+  case "$LAST_PAUSE_REASON" in
+    "checkpoint")
+      echo "Explicit checkpoint requested"
+      ;;
+    "decision")
+      echo "Decision needed - Claude wants your input"
+      ;;
+    "low_confidence")
+      echo "Low confidence - Claude is uncertain about approach"
+      ;;
+    "interactive")
+      echo "Interactive mode - pausing after every task"
+      ;;
+    "periodic")
+      echo "Periodic checkpoint (every $PAUSE_INTERVAL tasks)"
+      ;;
+    *)
+      echo "Pause requested"
+      ;;
+  esac
+}
+
+# Extract signal details from output
+# Format: SIGNAL_NAME|reason|details
+extract_signal_details() {
+  local output="$1"
+  local signal_type="$2"
+
+  local signal_line
+  signal_line=$(echo "$output" | grep -o "${signal_type}|[^|]*|[^|]*" | head -1)
+
+  if [ -n "$signal_line" ]; then
+    local reason
+    reason=$(echo "$signal_line" | cut -d'|' -f2)
+    local details
+    details=$(echo "$signal_line" | cut -d'|' -f3)
+    echo "Reason: $reason"
+    [ -n "$details" ] && echo "Details: $details"
+  fi
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Pause Handler
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Handle a pause point with user interaction
+# Returns: 0 = continue, 1 = quit, 2 = skip task
+handle_pause() {
+  local output="$1"
+  local iteration="$2"
+  local task_count="$3"
+
+  echo ""
+  echo -e "${MAGENTA}╔═══════════════════════════════════════════════════════════════╗${RESET}"
+  echo -e "${MAGENTA}║  ${BOLD}PAUSE POINT${RESET}${MAGENTA}                                                  ║${RESET}"
+  echo -e "${MAGENTA}╚═══════════════════════════════════════════════════════════════╝${RESET}"
+  echo ""
+
+  # Show pause reason
+  local reason
+  reason=$(get_pause_reason)
+  echo -e "${YELLOW}Why paused:${RESET} $reason"
+  echo ""
+
+  # Show signal details if present
+  if [ "$LAST_PAUSE_REASON" = "decision" ]; then
+    echo -e "${CYAN}Decision details:${RESET}"
+    extract_signal_details "$output" "DECISION_NEEDED"
+    echo ""
+  elif [ "$LAST_PAUSE_REASON" = "low_confidence" ]; then
+    echo -e "${CYAN}Uncertainty details:${RESET}"
+    extract_signal_details "$output" "LOW_CONFIDENCE"
+    echo ""
+  fi
+
+  # Show progress
+  echo -e "${BLUE}Progress:${RESET} Iteration $iteration, Tasks completed: $task_count"
+  echo ""
+
+  # Show menu
+  echo -e "${BOLD}Options:${RESET}"
+  echo -e "  ${GREEN}[c]${RESET} Continue to next task"
+  echo -e "  ${CYAN}[d]${RESET} Discuss (spawn fresh Claude for conversation)"
+  echo -e "  ${YELLOW}[s]${RESET} Skip current task"
+  echo -e "  ${RED}[q]${RESET} Quit and save state"
+  echo ""
+
+  # Use timeout if available, otherwise standard read
+  local response
+  if declare -f read_with_timeout &> /dev/null; then
+    response=$(read_with_timeout "Your choice [c/d/s/q]: " "c")
+  else
+    echo -n "Your choice [c/d/s/q]: "
+    read -r response
+    response="${response:-c}"
+  fi
+
+  case "${response,,}" in
+    c|continue)
+      echo -e "${GREEN}Continuing...${RESET}"
+      return 0
+      ;;
+    d|discuss)
+      echo -e "${CYAN}Launching discussion mode...${RESET}"
+      # Check if discuss.sh is available
+      if declare -f spawn_discussion &> /dev/null; then
+        spawn_discussion "$output" "$iteration"
+        # After discussion, show menu again
+        handle_pause "$output" "$iteration" "$task_count"
+        return $?
+      else
+        echo -e "${YELLOW}Discussion mode not available. Continuing...${RESET}"
+        return 0
+      fi
+      ;;
+    s|skip)
+      echo -e "${YELLOW}Skipping current task...${RESET}"
+      record_task_skipped "$iteration"
+      return 2
+      ;;
+    q|quit)
+      echo -e "${RED}Saving state and exiting...${RESET}"
+      update_state "status" "paused"
+      return 1
+      ;;
+    *)
+      echo -e "${YELLOW}Unknown option. Continuing...${RESET}"
+      return 0
+      ;;
+  esac
+}
+
+# Record that a task was skipped
+record_task_skipped() {
+  local iteration="$1"
+  local now
+  now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  if [ -n "$HISTORY_FILE" ]; then
+    echo "{\"type\":\"task_skipped\",\"iteration\":$iteration,\"timestamp\":\"$now\"}" >> "$HISTORY_FILE"
+  fi
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Mode Display
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Get mode display name with description
+get_mode_display() {
+  case "$LOOP_MODE" in
+    "$MODE_AUTO")
+      echo "Automated (pauses only on explicit checkpoints)"
+      ;;
+    "$MODE_INTERACTIVE")
+      echo "Interactive (pauses after every task)"
+      ;;
+    "$MODE_HYBRID")
+      echo "Hybrid (pauses on decisions, low confidence, every ${PAUSE_INTERVAL} tasks)"
+      ;;
+    *)
+      echo "$LOOP_MODE"
+      ;;
+  esac
+}
+
+# Validate mode value
+validate_mode() {
+  local mode="$1"
+
+  case "$mode" in
+    "$MODE_AUTO"|"$MODE_INTERACTIVE"|"$MODE_HYBRID")
+      return 0
+      ;;
+    *)
+      echo -e "${RED}Invalid mode: $mode${RESET}"
+      echo "Valid modes: auto, interactive, hybrid"
+      return 1
+      ;;
+  esac
+}
+
+# Set loop mode with validation
+set_loop_mode() {
+  local mode="$1"
+
+  if validate_mode "$mode"; then
+    LOOP_MODE="$mode"
+    echo -e "${GREEN}Loop mode set to: $(get_mode_display)${RESET}"
+    return 0
+  fi
+
+  return 1
+}

package/files/loop/lib/session-end.sh

@@ -0,0 +1,248 @@
+#!/usr/bin/env bash
+#
+# Merlin Loop - Session End Protocol
+# Enforces commit + sync + checkpoint at every task end
+# Part of Merlin Pro v1.0
+#
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Configuration
+# ═══════════════════════════════════════════════════════════════════════════════
+
+SESSION_END_AUTO_COMMIT="${MERLIN_AUTO_COMMIT:-true}"
+SESSION_END_AUTO_PUSH="${MERLIN_AUTO_PUSH:-true}"
+SESSION_END_AUTO_CHECKPOINT="${MERLIN_AUTO_CHECKPOINT:-true}"
+SESSION_END_REQUIRE_CLEAN="${MERLIN_REQUIRE_CLEAN:-false}"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Session End Protocol
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Main session end protocol - call this after every task
+session_end_protocol() {
+  local task_description="${1:-Task completed}"
+  local task_id="${2:-}"
+  local files_changed="${3:-}"  # Comma-separated list or empty for auto-detect
+
+  echo ""
+  echo -e "${MAGENTA}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+  echo -e "${BOLD}📦 SESSION END PROTOCOL${RESET}"
+  echo -e "${MAGENTA}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+  echo ""
+
+  local success=true
+  local commit_hash=""
+
+  # Step 1: Check for uncommitted changes
+  echo -e "${CYAN}[1/5]${RESET} Checking for changes..."
+  local has_changes
+  has_changes=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+
+  if [ "$has_changes" -eq 0 ]; then
+    echo -e "      ${GREEN}✓${RESET} No uncommitted changes"
+  else
+    echo -e "      ${YELLOW}!${RESET} Found ${has_changes} changed files"
+
+    # Step 2: Auto-commit if enabled
+    if [ "$SESSION_END_AUTO_COMMIT" == "true" ]; then
+      echo -e "${CYAN}[2/5]${RESET} Committing changes..."
+
+      # Stage all changes (or specific files if provided)
+      if [ -n "$files_changed" ]; then
+        # Stage specific files
+        IFS=',' read -ra FILES <<< "$files_changed"
+        for file in "${FILES[@]}"; do
+          git add "$file" 2>/dev/null || true
+        done
+      else
+        # Stage all changes
+        git add -A
+      fi
+
+      # Create commit message
+      local commit_msg="feat: ${task_description}"
+      if [ -n "$task_id" ]; then
+        commit_msg="${commit_msg}
+
+Task: ${task_id}
+Co-Authored-By: Merlin Loop <noreply@merlin.build>"
+      fi
+
+      # Commit
+      if git commit -m "$commit_msg" 2>/dev/null; then
+        commit_hash=$(git rev-parse HEAD 2>/dev/null)
+        echo -e "      ${GREEN}✓${RESET} Committed: ${commit_hash:0:7}"
+      else
+        echo -e "      ${YELLOW}⚠${RESET} Commit failed (pre-commit hook or no changes)"
+        success=false
+      fi
+    else
+      echo -e "${CYAN}[2/5]${RESET} Auto-commit disabled, skipping"
+    fi
+  fi
+
+  # Step 3: Push to remote
+  if [ "$SESSION_END_AUTO_PUSH" == "true" ] && [ -n "$commit_hash" ]; then
+    echo -e "${CYAN}[3/5]${RESET} Pushing to remote..."
+
+    if git push 2>/dev/null; then
+      echo -e "      ${GREEN}✓${RESET} Pushed to remote"
+    else
+      echo -e "      ${YELLOW}⚠${RESET} Push failed (network or permissions)"
+    fi
+  else
+    echo -e "${CYAN}[3/5]${RESET} Push skipped"
+  fi
+
+  # Step 4: Record commit to Sights activity tracking
+  echo -e "${CYAN}[4/5]${RESET} Recording to Sights..."
+  if [ -n "$commit_hash" ] && type record_last_commit &> /dev/null; then
+    if record_last_commit "$task_id" "merlin-loop" "loop-agent"; then
+      echo -e "      ${GREEN}✓${RESET} Recorded in Sights activity"
+    else
+      echo -e "      ${YELLOW}⚠${RESET} Sights recording failed (API key or connection)"
+    fi
+  else
+    echo -e "      ${DIM}Skipped (no commit or Sights not available)${RESET}"
+  fi
+
+  # Step 5: Save checkpoint
+  if [ "$SESSION_END_AUTO_CHECKPOINT" == "true" ]; then
+    echo -e "${CYAN}[5/5]${RESET} Saving checkpoint..."
+
+    if type save_checkpoint &> /dev/null; then
+      # Get current task info
+      local current_phase=""
+      local current_task=""
+
+      if [ -f "$STATE_FILE" ] && command -v jq &> /dev/null; then
+        current_phase=$(jq -r '.current_phase // empty' "$STATE_FILE" 2>/dev/null || echo "")
+        current_task=$(jq -r '.current_task // empty' "$STATE_FILE" 2>/dev/null || echo "")
+      fi
+
+      # Get files as JSON array
+      local files_json="[]"
+      if [ -n "$files_changed" ]; then
+        files_json=$(echo "$files_changed" | jq -R 'split(",")' 2>/dev/null || echo "[]")
+      elif [ -n "$commit_hash" ]; then
+        files_json=$(git diff-tree --no-commit-id --name-only -r "$commit_hash" 2>/dev/null | jq -R -s 'split("\n") | map(select(. != ""))' || echo "[]")
+      fi
+
+      if save_checkpoint "$task_description" "$current_phase" "$current_task" "$files_json" "merlin-loop"; then
+        echo -e "      ${GREEN}✓${RESET} Checkpoint saved to cloud"
+      else
+        echo -e "      ${YELLOW}⚠${RESET} Checkpoint save failed"
+      fi
+    else
+      echo -e "      ${DIM}Skipped (checkpoint function not available)${RESET}"
+    fi
+  else
+    echo -e "${CYAN}[5/5]${RESET} Auto-checkpoint disabled, skipping"
+  fi
+
+  # Step 6: Release task claim (if held)
+  if [ -n "$task_id" ] && type release_task &> /dev/null; then
+    release_task "$task_id" 2>/dev/null || true
+  fi
+
+  echo ""
+  echo -e "${MAGENTA}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+
+  if [ "$success" == "true" ]; then
+    echo -e "${GREEN}✅ Session end protocol complete${RESET}"
+  else
+    echo -e "${YELLOW}⚠️  Session end protocol completed with warnings${RESET}"
+  fi
+
+  echo -e "${MAGENTA}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+  echo ""
+
+  return 0
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Quick Protocol (minimal version)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Quick session end - just commit and checkpoint, no visual output
+session_end_quick() {
+  local task_description="${1:-Task completed}"
+  local task_id="${2:-}"
+
+  # Check for changes
+  local has_changes
+  has_changes=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+
+  if [ "$has_changes" -gt 0 ] && [ "$SESSION_END_AUTO_COMMIT" == "true" ]; then
+    git add -A
+    git commit -m "feat: ${task_description}" --quiet 2>/dev/null || true
+    git push --quiet 2>/dev/null || true
+    record_last_commit "$task_id" "merlin-loop" "loop-agent" 2>/dev/null || true
+  fi
+
+  if [ "$SESSION_END_AUTO_CHECKPOINT" == "true" ] && type save_checkpoint &> /dev/null; then
+    save_checkpoint "$task_description" "" "" "[]" "merlin-loop" 2>/dev/null || true
+  fi
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Validation
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Check if work tree is clean (for strict mode)
+check_clean_worktree() {
+  local has_changes
+  has_changes=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+
+  if [ "$has_changes" -eq 0 ]; then
+    return 0
+  else
+    if [ "$SESSION_END_REQUIRE_CLEAN" == "true" ]; then
+      echo -e "${RED}Error: Work tree not clean. Commit or stash changes before continuing.${RESET}"
+      return 1
+    fi
+    return 0
+  fi
+}
+
+# Verify session end was successful
+verify_session_end() {
+  local errors=0
+
+  # Check if work tree is clean (if required)
+  if [ "$SESSION_END_REQUIRE_CLEAN" == "true" ]; then
+    local has_changes
+    has_changes=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$has_changes" -gt 0 ]; then
+      echo -e "${YELLOW}Warning: Uncommitted changes remain${RESET}"
+      ((errors++))
+    fi
+  fi
+
+  # Check if checkpoint was saved (if enabled)
+  if [ "$SESSION_END_AUTO_CHECKPOINT" == "true" ] && type fetch_checkpoint &> /dev/null; then
+    local checkpoint
+    checkpoint=$(fetch_checkpoint 2>/dev/null || echo "")
+    if [ -z "$checkpoint" ]; then
+      echo -e "${YELLOW}Warning: No checkpoint found${RESET}"
+      ((errors++))
+    fi
+  fi
+
+  return $errors
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Integration Hook
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Hook to call after Claude completes a task
+# Usage: after_task_hook "task description" "task-id" "file1.ts,file2.ts"
+after_task_hook() {
+  session_end_protocol "$@"
+}
+
+# Export for use by other scripts
+export -f session_end_protocol 2>/dev/null || true
+export -f session_end_quick 2>/dev/null || true
+export -f after_task_hook 2>/dev/null || true