autonomous-coding-toolkit 1.0.0

package/scripts/lib/common.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# common.sh — Shared utility functions for Code Factory scripts
+#
+# Source this in any script: source "$SCRIPT_DIR/lib/common.sh"
+#
+# Functions:
+#   detect_project_type <dir>              -> "python"|"node"|"make"|"bash"|"unknown"
+#   strip_json_fences                      -> stdin filter: remove ```json wrappers
+#   check_memory_available <threshold_gb>  -> exit 0 if available >= threshold, 1 if low, 2 if unknown
+#   require_command <cmd> [install_hint]   -> exit 1 with message if cmd not found
+
+detect_project_type() {
+    local dir="$1"
+    if [[ -f "$dir/pyproject.toml" || -f "$dir/setup.py" || -f "$dir/pytest.ini" ]]; then
+        echo "python"
+    elif [[ -f "$dir/package.json" ]]; then
+        echo "node"
+    elif [[ -f "$dir/Makefile" ]]; then
+        echo "make"
+    elif [[ -x "$dir/scripts/tests/run-all-tests.sh" ]] || compgen -G "$dir/scripts/tests/test-*.sh" >/dev/null 2>&1; then
+        echo "bash"
+    else
+        echo "unknown"
+    fi
+}
+
+strip_json_fences() {
+    sed '/^```json$/d; /^```$/d'
+}
+
+check_memory_available() {
+    local threshold_gb="${1:-4}"
+    local threshold_mb=$((threshold_gb * 1024))
+    local available_mb
+    available_mb=$(free -m 2>/dev/null | awk '/Mem:/{print $7}')
+    if [[ -z "$available_mb" ]]; then
+        # free command unavailable or produced no output — return -1 (unknown)
+        echo "WARNING: Cannot determine available memory (free command unavailable)" >&2
+        return 2
+    fi
+    if [[ "$available_mb" -ge "$threshold_mb" ]]; then
+        return 0
+    else
+        local available_display
+        available_display=$(awk "BEGIN {printf \"%.1f\", $available_mb / 1024}")
+        echo "WARNING: Low memory (${available_display}G available, need ${threshold_gb}G)" >&2
+        return 1
+    fi
+}
+
+require_command() {
+    local cmd="$1"
+    local hint="${2:-}"
+    if ! command -v "$cmd" >/dev/null 2>&1; then
+        echo "ERROR: Required command not found: $cmd" >&2
+        if [[ -n "$hint" ]]; then
+            echo "  Install with: $hint" >&2
+        fi
+        return 1
+    fi
+}

package/scripts/lib/cost-tracking.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# cost-tracking.sh — Per-batch cost tracking via Claude CLI JSONL session files
+#
+# Claude CLI stores session data in JSONL files at:
+#   ~/.claude/projects/<project>/<session-id>.jsonl
+# The last line with type "summary" contains token counts and cost.
+#
+# Functions:
+#   find_session_jsonl <session_id> <claude_dir>  -> path to JSONL file (empty if not found)
+#   extract_session_cost <session_id> <claude_dir> -> JSON: {input_tokens, output_tokens, cache_read_tokens, estimated_cost_usd, model, tracking_status}
+#   record_batch_cost <worktree> <batch_num> <session_id> [claude_dir]  -> updates .run-plan-state.json
+#   check_budget <worktree> <max_budget_usd>  -> exits 0 if under, 1 if over
+#   get_total_cost <worktree>  -> prints total_cost_usd from state
+
+find_session_jsonl() {
+    local session_id="$1" claude_dir="$2"
+    local found=""
+    # Search all project directories for the session JSONL
+    while IFS= read -r -d '' f; do
+        found="$f"
+        break
+    done < <(find "$claude_dir" -name "${session_id}.jsonl" -print0 2>/dev/null)
+    echo "$found"
+}
+
+extract_session_cost() {
+    local session_id="$1" claude_dir="$2"
+    local jsonl_path
+    jsonl_path=$(find_session_jsonl "$session_id" "$claude_dir")
+
+    if [[ -z "$jsonl_path" || ! -f "$jsonl_path" ]]; then
+        # Fix #39: tracking_status field distinguishes "broken tracking" from "true $0 cost"
+        # Fix #36: use jq --arg to safely interpolate session_id (no JSON injection)
+        echo "WARNING: cost-tracking: no JSONL file found for session $session_id" >&2
+        jq -n --arg sid "$session_id" \
+            '{input_tokens:0,output_tokens:0,cache_read_tokens:0,estimated_cost_usd:0,model:"unknown",session_id:$sid,tracking_status:"missing_file"}'
+        return 0
+    fi
+
+    # Fix #35: || true prevents grep exit-1 from killing set -e callers when no summary line exists
+    local summary
+    summary=$(grep '"type":"summary"' "$jsonl_path" | tail -1 || true)
+
+    if [[ -n "$summary" ]]; then
+        # Fix #36: use jq --arg for session_id to prevent JSON injection
+        # Fix #39: tracking_status:"found" confirms real data was retrieved
+        echo "$summary" | jq -c --arg sid "$session_id" '{
+            input_tokens: (.inputTokens // 0),
+            output_tokens: (.outputTokens // 0),
+            cache_read_tokens: (.cacheReadTokens // 0),
+            estimated_cost_usd: (.costUSD // 0),
+            model: (.model // "unknown"),
+            session_id: $sid,
+            tracking_status: "found"
+        }'
+    else
+        # Fix #36: use jq --arg for session_id to prevent JSON injection
+        # Fix #39: tracking_status:"no_summary" distinguishes from a real zero-cost session
+        echo "WARNING: cost-tracking: JSONL file exists but has no summary line for session $session_id" >&2
+        jq -n --arg sid "$session_id" \
+            '{input_tokens:0,output_tokens:0,cache_read_tokens:0,estimated_cost_usd:0,model:"unknown",session_id:$sid,tracking_status:"no_summary"}'
+    fi
+}
+
+record_batch_cost() {
+    local worktree="$1" batch_num="$2" session_id="$3"
+    local claude_dir="${4:-$HOME/.claude}"
+    local sf="$worktree/.run-plan-state.json"
+
+    if [[ ! -f "$sf" ]]; then
+        echo "WARNING: No state file at $sf" >&2
+        return 1
+    fi
+
+    local cost_json
+    cost_json=$(extract_session_cost "$session_id" "$claude_dir")
+
+    local tmp
+    tmp=$(mktemp)
+    # Fix #37: trap ensures temp file is cleaned up even if jq fails
+    trap 'rm -f "$tmp"' RETURN
+
+    # Fix #41: (... | add) // 0 handles empty .costs object (add on [] returns null, not 0)
+    jq --arg batch "$batch_num" --argjson cost "$cost_json" '
+        .costs //= {} |
+        .costs[$batch] = $cost |
+        .total_cost_usd = (([.costs[].estimated_cost_usd] | add) // 0)
+    ' "$sf" > "$tmp" && mv "$tmp" "$sf"
+}
+
+check_budget() {
+    local worktree="$1" max_budget="$2"
+    local sf="$worktree/.run-plan-state.json"
+
+    if [[ ! -f "$sf" ]]; then
+        return 0  # No state = no cost = under budget
+    fi
+
+    local total
+    total=$(jq -r '.total_cost_usd // 0' "$sf" 2>/dev/null) || total=""
+
+    # Fix #63: validate jq output is numeric — corrupted state must not bypass budget
+    if [[ -z "$total" ]] || ! [[ "$total" =~ ^[0-9]*\.?[0-9]+$ ]]; then
+        echo "WARNING: cost-tracking: corrupted total_cost_usd='$total' in state file — treating as budget exceeded" >&2
+        return 1
+    fi
+
+    # Fix #69: validate max_budget is numeric — prevent awk injection via CLI args
+    if ! [[ "$max_budget" =~ ^[0-9]*\.?[0-9]+$ ]]; then
+        echo "ERROR: cost-tracking: invalid max_budget='$max_budget'" >&2
+        return 1
+    fi
+
+    # Fix #40: check for bc; fall back to awk for float comparison if missing
+    if ! command -v bc >/dev/null 2>&1; then
+        echo "WARNING: cost-tracking: bc not found, using awk for budget comparison" >&2
+        # Safe: both values validated as numeric above
+        if awk "BEGIN {exit !(${total} > ${max_budget})}" 2>/dev/null; then
+            echo "BUDGET EXCEEDED: \$${total} spent of \$${max_budget} limit" >&2
+            return 1
+        fi
+        return 0
+    fi
+
+    # Compare using bc (bash can't do float comparison natively)
+    if (( $(echo "$total > $max_budget" | bc -l) )); then
+        echo "BUDGET EXCEEDED: \$${total} spent of \$${max_budget} limit" >&2
+        return 1
+    fi
+    return 0
+}
+
+get_total_cost() {
+    local worktree="$1"
+    local sf="$worktree/.run-plan-state.json"
+
+    if [[ ! -f "$sf" ]]; then
+        echo "0"
+        return 0
+    fi
+
+    local val
+    val=$(jq -r '.total_cost_usd // 0' "$sf" 2>/dev/null) || val=""
+
+    # Fix #63: validate output is numeric — don't silently return "0" on corrupted state
+    if [[ -n "$val" ]] && [[ "$val" =~ ^[0-9]*\.?[0-9]+$ ]]; then
+        echo "$val"
+    else
+        echo "WARNING: cost-tracking: corrupted total_cost_usd='$val' in $sf" >&2
+        echo "error"
+        return 1
+    fi
+}

package/scripts/lib/ollama.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# ollama.sh — Shared Ollama API interaction for Code Factory scripts
+#
+# Requires: common.sh sourced first (for strip_json_fences)
+#
+# Functions:
+#   ollama_build_payload <model> <prompt>  -> JSON payload string
+#   ollama_parse_response                  -> stdin filter: extract .response from Ollama JSON
+#   ollama_extract_json                    -> stdin filter: parse response, strip fences, validate JSON
+#   ollama_query <model> <prompt>          -> full query: build payload, call API, return response text
+#   ollama_query_json <model> <prompt>     -> full query + JSON extraction
+
+OLLAMA_DIRECT_URL="${OLLAMA_DIRECT_URL:-http://localhost:11434}"
+OLLAMA_QUEUE_URL="${OLLAMA_QUEUE_URL:-http://localhost:7683}"
+
+ollama_build_payload() {
+    local model="$1" prompt="$2"
+    jq -n --arg model "$model" --arg prompt "$prompt" \
+        '{model: $model, prompt: $prompt, stream: false}'
+}
+
+ollama_parse_response() {
+    jq -r '.response // empty'
+}
+
+ollama_extract_json() {
+    local text
+    text=$(cat)
+    # Strip fences
+    text=$(echo "$text" | strip_json_fences)
+    # Validate JSON
+    if echo "$text" | jq . >/dev/null 2>&1; then
+        echo "$text"
+    else
+        echo "WARNING: ollama_extract_json: invalid JSON in response" >&2
+        echo ""
+    fi
+}
+
+ollama_query() {
+    local model="$1" prompt="$2"
+    local payload api_url response
+
+    payload=$(ollama_build_payload "$model" "$prompt")
+
+    # Prefer queue if available
+    if curl -s -o /dev/null -w '%{http_code}' --connect-timeout 5 --max-time 10 "$OLLAMA_QUEUE_URL/health" 2>/dev/null | grep -q "200"; then
+        api_url="$OLLAMA_QUEUE_URL/api/generate"
+    else
+        api_url="$OLLAMA_DIRECT_URL/api/generate"
+    fi
+
+    response=$(curl -s "$api_url" -d "$payload" --connect-timeout 10 --max-time 300)
+    echo "$response" | ollama_parse_response
+}
+
+ollama_query_json() {
+    local model="$1" prompt="$2"
+    ollama_query "$model" "$prompt" | ollama_extract_json
+}

package/scripts/lib/progress-writer.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# progress-writer.sh — Structured progress.txt writer/reader
+#
+# Provides structured batch progress tracking with machine-readable sections.
+# Format:
+#   ## Batch N: <title> (YYYY-MM-DDTHH:MM:SSZ)
+#   ### Files Modified
+#   - path/to/file (created|modified|deleted)
+#   ### Decisions
+#   - decision: rationale
+#   ### Issues Encountered
+#   - issue → resolution
+#   ### State
+#   - Tests: N passing
+#   - Duration: Ns
+#   - Cost: $N.NN
+#
+# Functions:
+#   write_batch_progress <worktree> <batch_num> <title>
+#   append_progress_section <worktree> <section> <content>
+#   read_batch_progress <worktree> <batch_num>
+#
+# NOTE: write_batch_progress and append_progress_section are called by
+# run-plan-headless.sh at batch start and after quality gate passes.
+
+# Write a batch header with timestamp to progress.txt
+# Usage: write_batch_progress <worktree> <batch_num> <title>
+# Returns: 0 on success, 1 on I/O error
+write_batch_progress() {
+  local worktree="$1" batch_num="$2" title="$3"
+  local progress_file="$worktree/progress.txt"
+  local timestamp
+  timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+  # Ensure trailing newline before new batch header (if file exists and is non-empty)
+  if [[ -s "$progress_file" ]]; then
+    # Add blank line separator between batches
+    echo "" >> "$progress_file" || {
+      echo "ERROR: Failed to write to $progress_file" >&2
+      return 1
+    }
+  fi
+
+  echo "## Batch ${batch_num}: ${title} (${timestamp})" >> "$progress_file" || {
+    echo "ERROR: Failed to write batch header to $progress_file" >&2
+    return 1
+  }
+}
+
+# Append a named section under the most recent batch header
+# Usage: append_progress_section <worktree> <section> <content>
+# section: "Files Modified", "Decisions", "Issues Encountered", "State"
+# Returns: 0 on success, 1 on I/O error
+append_progress_section() {
+  local worktree="$1" section="$2" content="$3"
+  local progress_file="$worktree/progress.txt"
+
+  echo "### ${section}" >> "$progress_file" || {
+    echo "ERROR: Failed to write section header to $progress_file" >&2
+    return 1
+  }
+  echo "$content" >> "$progress_file" || {
+    echo "ERROR: Failed to write section content to $progress_file" >&2
+    return 1
+  }
+}
+
+# Extract a single batch's content from progress.txt using awk
+# Returns everything from "## Batch N: <title> (timestamp)" up to (but not
+# including) the next "## Batch" header or EOF.
+#
+# The pattern requires the timestamp in parens at end to avoid false matches
+# when progress content itself mentions "## Batch N:" in notes.
+#
+# Exit codes:
+#   0 — batch found (content printed, may be empty if batch has no body)
+#   1 — batch not found in file
+#   2 — progress.txt file does not exist
+#
+# Usage: read_batch_progress <worktree> <batch_num>
+read_batch_progress() {
+  local worktree="$1" batch_num="$2"
+  local progress_file="$worktree/progress.txt"
+
+  # Validate batch_num is a positive integer
+  if [[ ! "$batch_num" =~ ^[0-9]+$ ]]; then
+    echo "ERROR: batch_num must be a positive integer, got: '$batch_num'" >&2
+    return 1
+  fi
+
+  if [[ ! -f "$progress_file" ]]; then
+    return 2
+  fi
+
+  # Use the timestamp-anchored pattern to avoid false matches on content.
+  # Header format: ## Batch N: <title> (YYYY-MM-DDTHH:MM:SSZ)
+  # The awk sets found=1 when the target header is matched, then prints
+  # subsequent lines until another timestamped batch header is encountered.
+  local found
+  found=$(awk -v batch="$batch_num" '
+    /^## Batch [0-9]+: .+ \([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z\)$/ {
+      # Extract batch number: field 3, strip trailing colon
+      n = $3
+      sub(/:$/, "", n)
+      if (n == batch) {
+        printing = 1
+        print
+        next
+      } else if (printing) {
+        exit
+      }
+    }
+    printing { print }
+  ' "$progress_file")
+
+  if [[ -z "$found" ]]; then
+    # Check whether the batch header exists at all (empty body vs not found)
+    if grep -qE "^## Batch ${batch_num}: .+ \([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z\)$" "$progress_file" 2>/dev/null; then
+      # Batch exists but has no body content — return 0, print nothing
+      return 0
+    else
+      return 1
+    fi
+  fi
+
+  echo "$found"
+  return 0
+}

package/scripts/lib/run-plan-context.sh

@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+# run-plan-context.sh — Per-batch context assembler for run-plan
+#
+# Assembles relevant context for a batch agent within a token budget.
+# Reads: state file, progress.txt, git log, context_refs, failure patterns.
+# Outputs: markdown section for CLAUDE.md injection.
+#
+# Functions:
+#   generate_batch_context <plan_file> <batch_num> <worktree> -> markdown string
+#   record_failure_pattern <worktree> <batch_title> <failure_type> <winning_fix>
+
+TOKEN_BUDGET_CHARS=10000  # ~2500 tokens
+
+generate_batch_context() {
+    local plan_file="$1" batch_num="$2" worktree="$3"
+    local context=""
+    local chars_used=0
+
+    context+="## Run-Plan: Batch $batch_num"$'\n\n'
+
+    # 1. Directives from state (highest priority)
+    local state_file="$worktree/.run-plan-state.json"
+    if [[ -f "$state_file" ]]; then
+        local prev_test_count
+        prev_test_count=$(jq -r '[.batches[].test_count // 0] | max' "$state_file" 2>/dev/null || echo "0")
+        if [[ "$prev_test_count" -gt 0 ]]; then
+            context+="**Directive:** tests must stay above $prev_test_count (current high water mark)"$'\n\n'
+        fi
+
+        # Prior batch summary (most recent 2 batches only)
+        local start_batch=$(( batch_num - 2 ))
+        [[ $start_batch -lt 1 ]] && start_batch=1
+        for ((b = start_batch; b < batch_num; b++)); do
+            local passed duration tests
+            passed=$(jq -r ".batches[\"$b\"].passed // false" "$state_file" 2>/dev/null)
+            tests=$(jq -r ".batches[\"$b\"].test_count // 0" "$state_file" 2>/dev/null)
+            duration=$(jq -r ".batches[\"$b\"].duration // 0" "$state_file" 2>/dev/null)
+            if [[ "$passed" == "true" ]]; then
+                context+="Batch $b: PASSED ($tests tests, ${duration}s)"$'\n'
+            fi
+        done
+        context+=$'\n'
+    fi
+
+    # 2. Failure patterns (cross-run learning)
+    local patterns_file="$worktree/logs/failure-patterns.json"
+    if [[ -f "$patterns_file" ]]; then
+        local batch_title
+        batch_title=$(get_batch_title "$plan_file" "$batch_num" 2>/dev/null || echo "")
+        local title_lower
+        title_lower=$(echo "$batch_title" | tr '[:upper:]' '[:lower:]')
+
+        # Match failure patterns by batch title keywords
+        local matches
+        matches=$(jq -r --arg title "$title_lower" \
+            '.[] | select(.batch_title_pattern as $p | $title | contains($p)) | "WARNING: Previously failed with \(.failure_type) (\(.frequency)x). Fix that worked: \(.winning_fix)"' \
+            "$patterns_file" 2>/dev/null || true)
+        if [[ -n "$matches" ]]; then
+            context+="### Known Failure Patterns"$'\n'
+            context+="$matches"$'\n\n'
+        fi
+    fi
+
+    chars_used=${#context}
+
+    # 2.5. MAB lessons (from competing agent runs)
+    local mab_lessons_file="$worktree/logs/mab-lessons.json"
+    if [[ -f "$mab_lessons_file" ]]; then
+        local mab_count
+        mab_count=$(jq 'length' "$mab_lessons_file" 2>/dev/null || echo "0")
+        if [[ "$mab_count" -gt 0 ]]; then
+            local mab_section="### MAB Lessons"$'\n'
+            mab_section+=$(jq -r '
+                sort_by(-.occurrences // 0) | .[0:5] | .[] |
+                "- **\(.pattern)** (\(.context // "general")): \(.recommendation // .winner // "")"
+            ' "$mab_lessons_file" 2>/dev/null || true)
+            mab_section+=$'\n\n'
+            if [[ $((chars_used + ${#mab_section})) -lt $TOKEN_BUDGET_CHARS ]]; then
+                context+="$mab_section"
+                chars_used=$((chars_used + ${#mab_section}))
+            fi
+        fi
+    fi
+
+    # 2.6. Research warnings (from tasks/research-*.json)
+    local research_files
+    research_files=$(find "$worktree/tasks" -name 'research-*.json' 2>/dev/null || true)
+    if [[ -n "$research_files" ]]; then
+        local research_section=""
+        while IFS= read -r rfile; do
+            [[ -z "$rfile" ]] && continue
+            local warnings
+            warnings=$(jq -r '.warnings[]? // empty' "$rfile" 2>/dev/null || true)
+            if [[ -n "$warnings" ]]; then
+                local feature_name
+                feature_name=$(jq -r '.feature // "unknown"' "$rfile" 2>/dev/null || echo "unknown")
+                research_section+="### Research Warnings ($feature_name)"$'\n'
+                while IFS= read -r w; do
+                    research_section+="- $w"$'\n'
+                done <<< "$warnings"
+                research_section+=$'\n'
+            fi
+        done <<< "$research_files"
+        if [[ -n "$research_section" ]] && [[ $((chars_used + ${#research_section})) -lt $TOKEN_BUDGET_CHARS ]]; then
+            context+="$research_section"
+            chars_used=$((chars_used + ${#research_section}))
+        fi
+    fi
+
+    # 3. Context refs file contents (if budget allows)
+    local refs
+    refs=$(get_batch_context_refs "$plan_file" "$batch_num" 2>/dev/null || true)
+    if [[ -n "$refs" ]]; then
+        local refs_section="### Referenced Files"$'\n'
+        while IFS= read -r ref_file; do
+            # Trim whitespace using parameter expansion (xargs word-splits on spaces — #60)
+            ref_file="${ref_file#"${ref_file%%[![:space:]]*}"}"
+            ref_file="${ref_file%"${ref_file##*[![:space:]]}"}"
+            [[ -z "$ref_file" ]] && continue
+            local full_path="$worktree/$ref_file"
+            if [[ -f "$full_path" ]]; then
+                local file_content
+                file_content=$(head -50 "$full_path" 2>/dev/null || true)
+                local addition
+                addition=$'\n'"**$ref_file:**"$'\n'"$file_content"$'\n'
+                if [[ $(( chars_used + ${#refs_section} + ${#addition} )) -lt $TOKEN_BUDGET_CHARS ]]; then
+                    refs_section+="$addition"
+                fi
+            fi
+        done <<< "$refs"
+        context+="$refs_section"$'\n'
+    fi
+
+    chars_used=${#context}
+
+    # 4. Git log (if budget allows)
+    if [[ $(( chars_used + 500 )) -lt $TOKEN_BUDGET_CHARS ]]; then
+        local git_log
+        git_log=$(git -C "$worktree" log --oneline -5 2>/dev/null || true)
+        if [[ -n "$git_log" ]]; then
+            context+="### Recent Commits"$'\n'
+            context+="$git_log"$'\n\n'
+        fi
+    fi
+
+    chars_used=${#context}
+
+    # 5. Progress.txt (if budget allows — structured read for last 2 batches)
+    # NOTE: No tail fallback — injecting lines from an unknown batch contaminates
+    # context with wrong-batch data. If structured read returns empty, no progress
+    # exists for the requested batches (#54).
+    if [[ $(( chars_used + 500 )) -lt $TOKEN_BUDGET_CHARS ]]; then
+        local progress_file="$worktree/progress.txt"
+        if [[ -f "$progress_file" ]]; then
+            local progress=""
+            if type read_batch_progress &>/dev/null; then
+                # Structured read: last 2 batches
+                local pb_start=$(( batch_num - 2 ))
+                [[ $pb_start -lt 1 ]] && pb_start=1
+                for ((pb = pb_start; pb < batch_num; pb++)); do
+                    local pb_content
+                    pb_content=$(read_batch_progress "$worktree" "$pb" 2>/dev/null || true)
+                    if [[ -n "$pb_content" ]]; then
+                        progress+="$pb_content"$'\n'
+                    fi
+                done
+            fi
+            # No fallback to tail: structured read returning empty means no progress
+            # for the requested batches (not a failure condition).
+            if [[ -n "$progress" ]]; then
+                context+="### Progress Notes"$'\n'
+                context+="$progress"$'\n\n'
+            fi
+        fi
+    fi
+
+    echo "$context"
+}
+
+record_failure_pattern() {
+    local worktree="$1" batch_title="$2" failure_type="$3" winning_fix="$4"
+    local patterns_file="$worktree/logs/failure-patterns.json"
+    local title_lower
+    title_lower=$(echo "$batch_title" | tr '[:upper:]' '[:lower:]')
+
+    mkdir -p "$(dirname "$patterns_file")"
+
+    if [[ ! -f "$patterns_file" ]]; then
+        echo "[]" > "$patterns_file"
+    fi
+
+    # Check if pattern already exists
+    local existing
+    existing=$(jq -r --arg t "$title_lower" --arg f "$failure_type" \
+        '[.[] | select(.batch_title_pattern == $t and .failure_type == $f)] | length' \
+        "$patterns_file" 2>/dev/null || echo "0")
+
+    if [[ "$existing" -gt 0 ]]; then
+        # Increment frequency — trap ensures temp file cleanup even if jq fails (#58)
+        local tmp
+        tmp=$(mktemp)
+        trap 'rm -f "$tmp"' RETURN
+        jq --arg t "$title_lower" --arg f "$failure_type" \
+            '[.[] | if .batch_title_pattern == $t and .failure_type == $f then .frequency += 1 else . end]' \
+            "$patterns_file" > "$tmp" && mv "$tmp" "$patterns_file"
+    else
+        # Add new pattern — trap ensures temp file cleanup even if jq fails (#58)
+        local tmp
+        tmp=$(mktemp)
+        trap 'rm -f "$tmp"' RETURN
+        jq --arg t "$title_lower" --arg f "$failure_type" --arg w "$winning_fix" \
+            '. += [{"batch_title_pattern": $t, "failure_type": $f, "frequency": 1, "winning_fix": $w}]' \
+            "$patterns_file" > "$tmp" && mv "$tmp" "$patterns_file"
+    fi
+}