prizmkit 1.1.1 → 1.1.4

package/bundled/dev-pipeline/run-refactor.sh

@@ -0,0 +1,787 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================
+# dev-pipeline/run-refactor.sh - Autonomous Refactor Pipeline Runner
+#
+# Drives the prizm-dev-team through iterative AI CLI sessions to
+# execute refactors from a refactor-list.json specification.
+#
+# Usage:
+#   ./run-refactor.sh run [refactor-list.json]          Run all refactors
+#   ./run-refactor.sh run <refactor-id> [options]       Run a single refactor
+#   ./run-refactor.sh status [refactor-list.json]       Show pipeline status
+#   ./run-refactor.sh reset                             Clear all state
+#
+# Environment Variables:
+#   MAX_RETRIES           Max retries per refactor (default: 3)
+#   SESSION_TIMEOUT       Session timeout in seconds (default: 0 = no limit)
+#   AI_CLI                AI CLI command name (auto-detected: cbc or claude)
+#   CODEBUDDY_CLI         Legacy alias for AI_CLI (deprecated, use AI_CLI instead)
+#   PRIZMKIT_PLATFORM     Force platform: 'codebuddy' or 'claude' (auto-detected)
+#   VERBOSE               Set to 1 to enable --verbose on AI CLI
+#   HEARTBEAT_INTERVAL    Heartbeat log interval in seconds (default: 30)
+#   HEARTBEAT_STALE_THRESHOLD  Heartbeat stale threshold in seconds (default: 600)
+#   LOG_CLEANUP_ENABLED   Run periodic log cleanup (default: 1)
+#   LOG_RETENTION_DAYS    Delete logs older than N days (default: 14)
+#   LOG_MAX_TOTAL_MB      Keep total logs under N MB via oldest-first cleanup (default: 1024)
+#   DEV_BRANCH            Custom dev branch name (default: auto-generated refactor/pipeline-{run_id})
+#   AUTO_PUSH             Auto-push to remote after successful refactor (default: 0). Set to 1 to enable.
+#   STRICT_BEHAVIOR_CHECK Force full test suite after each refactor item (default: 1)
+# ============================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+STATE_DIR="$SCRIPT_DIR/refactor-state"
+SCRIPTS_DIR="$SCRIPT_DIR/scripts"
+
+# Configuration
+MAX_RETRIES=${MAX_RETRIES:-3}
+SESSION_TIMEOUT=${SESSION_TIMEOUT:-0}
+HEARTBEAT_STALE_THRESHOLD=${HEARTBEAT_STALE_THRESHOLD:-600}
+HEARTBEAT_INTERVAL=${HEARTBEAT_INTERVAL:-30}
+LOG_CLEANUP_ENABLED=${LOG_CLEANUP_ENABLED:-1}
+LOG_RETENTION_DAYS=${LOG_RETENTION_DAYS:-14}
+LOG_MAX_TOTAL_MB=${LOG_MAX_TOTAL_MB:-1024}
+VERBOSE=${VERBOSE:-0}
+DEV_BRANCH=${DEV_BRANCH:-""}
+AUTO_PUSH=${AUTO_PUSH:-0}
+STRICT_BEHAVIOR_CHECK=${STRICT_BEHAVIOR_CHECK:-1}
+
+# Source shared common helpers (CLI/platform detection + logs + deps)
+source "$SCRIPT_DIR/lib/common.sh"
+prizm_detect_cli_and_platform
+
+# Source shared heartbeat library
+source "$SCRIPT_DIR/lib/heartbeat.sh"
+
+# Source shared branch library
+source "$SCRIPT_DIR/lib/branch.sh"
+
+# Detect stream-json support
+detect_stream_json_support "$CLI_CMD"
+
+# Refactor list path (set in main, used by cleanup trap)
+REFACTOR_LIST=""
+
+# Branch tracking (for cleanup on interrupt)
+_ORIGINAL_BRANCH=""
+_DEV_BRANCH_NAME=""
+
+# ============================================================
+# Shared: Spawn AI CLI session and wait for result
+# ============================================================
+
+spawn_and_wait_session() {
+    local refactor_id="$1"
+    local refactor_list="$2"
+    local session_id="$3"
+    local bootstrap_prompt="$4"
+    local session_dir="$5"
+    local max_retries="$6"
+    local base_branch="${7:-main}"
+
+    local session_log="$session_dir/logs/session.log"
+    local progress_json="$session_dir/logs/progress.json"
+
+    local verbose_flag=""
+    if [[ "$VERBOSE" == "1" ]]; then
+        verbose_flag="--verbose"
+    fi
+
+    local stream_json_flag=""
+    if [[ "$USE_STREAM_JSON" == "true" ]]; then
+        stream_json_flag="--output-format stream-json"
+        # claude-internal requires --verbose when using stream-json with -p/--print
+        verbose_flag="--verbose"
+    fi
+
+    local model_flag=""
+    if [[ -n "${MODEL:-}" ]]; then
+        model_flag="--model $MODEL"
+    fi
+
+    # Unset CLAUDECODE to prevent "nested session" error when launched from
+    # within an existing Claude Code session (e.g. via launch-refactor-daemon.sh).
+    unset CLAUDECODE 2>/dev/null || true
+
+    case "$CLI_CMD" in
+        *claude*)
+            # Claude Code: prompt via -p, --dangerously-skip-permissions for auto-accept
+            "$CLI_CMD" \
+                -p "$(cat "$bootstrap_prompt")" \
+                --dangerously-skip-permissions \
+                $verbose_flag \
+                $stream_json_flag \
+                $model_flag \
+                > "$session_log" 2>&1 &
+            ;;
+        *)
+            # CodeBuddy (cbc) and others: prompt via stdin, -y for auto-accept
+            "$CLI_CMD" \
+                --print \
+                -y \
+                $verbose_flag \
+                $stream_json_flag \
+                $model_flag \
+                < "$bootstrap_prompt" \
+                > "$session_log" 2>&1 &
+            ;;
+    esac
+    local cli_pid=$!
+
+    # Start progress parser (no-op if stream-json not supported)
+    start_progress_parser "$session_log" "$progress_json" "$SCRIPTS_DIR"
+    local parser_pid="${_PARSER_PID:-}"
+
+    # Timeout watchdog
+    local watcher_pid=""
+    if [[ $SESSION_TIMEOUT -gt 0 ]]; then
+        ( sleep "$SESSION_TIMEOUT" && kill -TERM "$cli_pid" 2>/dev/null ) &
+        watcher_pid=$!
+    fi
+
+    # Heartbeat monitor
+    start_heartbeat "$cli_pid" "$session_log" "$progress_json" "$HEARTBEAT_INTERVAL"
+    local heartbeat_pid="${_HEARTBEAT_PID:-}"
+
+    # Wait for AI CLI to finish
+    local exit_code=0
+    if wait "$cli_pid" 2>/dev/null; then
+        exit_code=0
+    else
+        exit_code=$?
+    fi
+
+    # Cleanup
+    [[ -n "$watcher_pid" ]] && kill "$watcher_pid" 2>/dev/null || true
+    stop_heartbeat "$heartbeat_pid"
+    stop_progress_parser "$parser_pid"
+    [[ -n "$watcher_pid" ]] && wait "$watcher_pid" 2>/dev/null || true
+
+    [[ $exit_code -eq 143 ]] && exit_code=124
+
+    # Session summary
+    if [[ -f "$session_log" ]]; then
+        local final_size=$(wc -c < "$session_log" 2>/dev/null | tr -d ' ')
+        local final_lines=$(wc -l < "$session_log" 2>/dev/null | tr -d ' ')
+        log_info "Session log: $final_lines lines, $((final_size / 1024))KB"
+    fi
+    log_info "exit_code=$exit_code"
+
+    # ── Determine session outcome from observable signals ──────────────
+    local session_status
+    local project_root
+    project_root="$(cd "$SCRIPT_DIR/.." && pwd)"
+    local default_branch="$base_branch"
+
+    if [[ $exit_code -eq 124 ]]; then
+        log_warn "Session timed out after ${SESSION_TIMEOUT}s"
+        session_status="timed_out"
+    elif [[ $exit_code -ne 0 ]]; then
+        log_warn "Session exited with code $exit_code"
+        session_status="crashed"
+    else
+        # Exit code 0 — check if the session actually produced commits
+        local has_commits=""
+        if git -C "$project_root" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+            has_commits=$(git -C "$project_root" log "${default_branch}..HEAD" --oneline 2>/dev/null | head -1)
+        fi
+
+        if [[ -n "$has_commits" ]]; then
+            session_status="success"
+        else
+            local uncommitted=""
+            uncommitted=$(git -C "$project_root" status --porcelain 2>/dev/null | head -1 || true)
+            if [[ -n "$uncommitted" ]]; then
+                log_warn "Session exited cleanly but produced no commits (uncommitted changes found) — auto-committing..."
+                git -C "$project_root" add -A 2>/dev/null || true
+                if git -C "$project_root" commit --no-verify -m "chore($refactor_id): auto-commit session work" 2>/dev/null; then
+                    log_info "Auto-commit succeeded"
+                    session_status="success"
+                else
+                    log_warn "Auto-commit failed — no changes to commit"
+                    session_status="crashed"
+                fi
+            else
+                log_warn "Session exited cleanly but produced no commits and no changes"
+                session_status="crashed"
+            fi
+        fi
+    fi
+
+    # ── Post-success validation ──────────────────────────────────────────
+    if [[ "$session_status" == "success" ]]; then
+        if git -C "$project_root" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+            local dirty_files=""
+            dirty_files=$(git -C "$project_root" status --porcelain 2>/dev/null || true)
+            if [[ -n "$dirty_files" ]]; then
+                log_info "Auto-committing remaining session artifacts..."
+                git -C "$project_root" add -A 2>/dev/null || true
+                git -C "$project_root" commit --no-verify --amend --no-edit 2>/dev/null \
+                    || git -C "$project_root" commit --no-verify -m "chore($refactor_id): include remaining session artifacts" 2>/dev/null \
+                    || true
+            fi
+        fi
+    fi
+
+    log_info "Session result: $session_status"
+
+    # Subagent detection
+    prizm_detect_subagents "$session_log"
+
+    # Update refactor status
+    python3 "$SCRIPTS_DIR/update-refactor-status.py" \
+        --refactor-list "$refactor_list" \
+        --state-dir "$STATE_DIR" \
+        --refactor-id "$refactor_id" \
+        --session-status "$session_status" \
+        --session-id "$session_id" \
+        --max-retries "$max_retries" \
+        --action update >/dev/null 2>&1 || true
+
+    # Commit refactor-list.json status update (pipeline management commit)
+    if ! git -C "$project_root" diff --quiet "$refactor_list" 2>/dev/null; then
+        git -C "$project_root" add "$refactor_list"
+        git -C "$project_root" commit --no-verify -m "chore($refactor_id): update refactor status" 2>/dev/null || true
+    fi
+
+    _SPAWN_RESULT="$session_status"
+}
+
+# ============================================================
+# Graceful Shutdown
+# ============================================================
+
+cleanup() {
+    echo ""
+    log_warn "Received interrupt signal. Saving state..."
+
+    # Kill all child processes (claude-internal, heartbeat, progress parser, etc.)
+    kill 0 2>/dev/null || true
+
+    # Log current branch info for recovery
+    if [[ -n "$_DEV_BRANCH_NAME" ]]; then
+        log_info "Development was on branch: $_DEV_BRANCH_NAME"
+        log_info "Original branch was: $_ORIGINAL_BRANCH"
+    fi
+
+    if [[ -n "$REFACTOR_LIST" && -f "$REFACTOR_LIST" ]]; then
+        python3 "$SCRIPTS_DIR/update-refactor-status.py" \
+            --refactor-list "$REFACTOR_LIST" \
+            --state-dir "$STATE_DIR" \
+            --action pause 2>/dev/null || true
+    fi
+
+    log_info "Refactor pipeline paused. Run './run-refactor.sh run' to resume."
+    exit 130
+}
+trap cleanup SIGINT SIGTERM
+
+# ============================================================
+# Dependency Check
+# ============================================================
+
+check_dependencies() {
+    prizm_check_common_dependencies "$CLI_CMD"
+    local _project_root
+    _project_root="$(cd "$SCRIPT_DIR/.." && pwd)"
+    prizm_ensure_git_repo "$_project_root"
+}
+
+run_log_cleanup() {
+    if [[ "$LOG_CLEANUP_ENABLED" != "1" ]]; then
+        return 0
+    fi
+
+    local cleanup_result
+    cleanup_result=$(python3 "$SCRIPTS_DIR/cleanup-logs.py" \
+        --state-dir "$STATE_DIR" \
+        --retention-days "$LOG_RETENTION_DAYS" \
+        --max-total-mb "$LOG_MAX_TOTAL_MB" 2>/dev/null) || {
+        log_warn "Log cleanup failed (continuing)"
+        return 0
+    }
+
+    local deleted reclaimed_kb
+    deleted=$(echo "$cleanup_result" | python3 -c "import sys,json; print(json.load(sys.stdin).get('deleted_files', 0))" 2>/dev/null || echo "0")
+    reclaimed_kb=$(echo "$cleanup_result" | python3 -c "import sys,json; print(int(json.load(sys.stdin).get('reclaimed_bytes', 0)/1024))" 2>/dev/null || echo "0")
+
+    if [[ "$deleted" -gt 0 ]]; then
+        log_info "Log cleanup: deleted $deleted files, reclaimed ${reclaimed_kb}KB"
+    fi
+}
+
+# ============================================================
+# run-one: Run a single refactor
+# ============================================================
+
+run_one() {
+    local refactor_id=""
+    local refactor_list=""
+    local dry_run=false
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --dry-run) dry_run=true; shift ;;
+            --timeout) shift; SESSION_TIMEOUT="${1:-0}"; shift ;;
+            R-*|r-*) refactor_id="$1"; shift ;;
+            *) refactor_list="$1"; shift ;;
+        esac
+    done
+
+    if [[ -z "$refactor_id" ]]; then
+        log_error "Refactor ID is required (e.g. R-001)"
+        echo ""
+        show_help
+        exit 1
+    fi
+
+    if [[ -z "$refactor_list" ]]; then
+        refactor_list="refactor-list.json"
+    fi
+    if [[ ! "$refactor_list" = /* ]]; then
+        refactor_list="$(pwd)/$refactor_list"
+    fi
+    REFACTOR_LIST="$refactor_list"
+
+    if [[ ! -f "$refactor_list" ]]; then
+        log_error "Refactor list not found: $refactor_list"
+        exit 1
+    fi
+
+    check_dependencies
+    run_log_cleanup
+
+    # Initialize state if needed
+    if [[ ! -f "$STATE_DIR/pipeline.json" ]]; then
+        log_info "Initializing refactor pipeline state..."
+        python3 "$SCRIPTS_DIR/init-refactor-pipeline.py" \
+            --refactor-list "$refactor_list" \
+            --state-dir "$STATE_DIR" >/dev/null 2>&1 || {
+            log_error "Failed to initialize refactor pipeline state"
+            exit 1
+        }
+
+        # Ensure state directory is gitignored
+        local _gitignore_path
+        _gitignore_path="$(cd "$SCRIPT_DIR/.." && pwd)/.gitignore"
+        local _state_rel
+        _state_rel=$(python3 -c "import os; print(os.path.relpath('$STATE_DIR', '$(cd "$SCRIPT_DIR/.." && pwd)'))" 2>/dev/null || echo "dev-pipeline/refactor-state")
+        if [[ -f "$_gitignore_path" ]]; then
+            if ! grep -qF "$_state_rel" "$_gitignore_path" 2>/dev/null; then
+                printf '\n# Pipeline runtime state (auto-added by dev-pipeline)\n%s/\n' "$_state_rel" >> "$_gitignore_path"
+            fi
+        else
+            printf '# Pipeline runtime state (auto-added by dev-pipeline)\n%s/\n' "$_state_rel" > "$_gitignore_path"
+        fi
+    fi
+
+    # Verify refactor exists
+    local refactor_title
+    refactor_title=$(python3 -c "
+import json, sys
+with open(sys.argv[1]) as f:
+    data = json.load(f)
+for item in data.get('refactors', []):
+    if item.get('id') == sys.argv[2]:
+        print(item.get('title', ''))
+        sys.exit(0)
+sys.exit(1)
+" "$refactor_list" "$refactor_id" 2>/dev/null) || {
+        log_error "Refactor $refactor_id not found in $refactor_list"
+        exit 1
+    }
+
+    local refactor_complexity
+    refactor_complexity=$(python3 -c "
+import json, sys
+with open(sys.argv[1]) as f:
+    data = json.load(f)
+for item in data.get('refactors', []):
+    if item.get('id') == sys.argv[2]:
+        print(item.get('complexity', 'medium'))
+        sys.exit(0)
+sys.exit(1)
+" "$refactor_list" "$refactor_id" 2>/dev/null) || refactor_complexity="medium"
+
+    # Reset refactor status
+    python3 "$SCRIPTS_DIR/update-refactor-status.py" \
+        --refactor-list "$refactor_list" \
+        --state-dir "$STATE_DIR" \
+        --refactor-id "$refactor_id" \
+        --action reset >/dev/null 2>&1 || true
+
+    # Generate bootstrap prompt
+    local run_id session_id session_dir bootstrap_prompt
+    run_id=$(jq -r '.run_id' "$STATE_DIR/pipeline.json")
+    session_id="${refactor_id}-$(date +%Y%m%d%H%M%S)"
+    session_dir="$STATE_DIR/refactors/$refactor_id/sessions/$session_id"
+    mkdir -p "$session_dir/logs"
+
+    bootstrap_prompt="$session_dir/bootstrap-prompt.md"
+
+    log_info "Generating refactor bootstrap prompt..."
+    python3 "$SCRIPTS_DIR/generate-refactor-prompt.py" \
+        --refactor-list "$refactor_list" \
+        --refactor-id "$refactor_id" \
+        --session-id "$session_id" \
+        --run-id "$run_id" \
+        --retry-count 0 \
+        --resume-phase "null" \
+        --state-dir "$STATE_DIR" \
+        --output "$bootstrap_prompt" >/dev/null 2>&1
+
+    if [[ "$dry_run" == true ]]; then
+        echo ""
+        echo -e "${BOLD}════════════════════════════════════════════════════${NC}"
+        echo -e "${BOLD}  Dry Run: $refactor_id — $refactor_title${NC}"
+        echo -e "${BOLD}  Complexity: $refactor_complexity${NC}"
+        echo -e "${BOLD}════════════════════════════════════════════════════${NC}"
+        echo ""
+        log_info "Bootstrap prompt written to:"
+        echo "  $bootstrap_prompt"
+        echo ""
+        log_success "Dry run complete. Inspect full prompt with:"
+        echo "  cat $bootstrap_prompt"
+        return 0
+    fi
+
+    echo ""
+    echo -e "${BOLD}════════════════════════════════════════════════════${NC}"
+    echo -e "${BOLD}  Refactor: $refactor_id — $refactor_title${NC}"
+    echo -e "${BOLD}  Complexity: $refactor_complexity${NC}"
+    echo -e "${BOLD}════════════════════════════════════════════════════${NC}"
+    log_info "Session ID: $session_id"
+    log_info "Prompt: $bootstrap_prompt"
+    log_info "Log: $session_dir/logs/session.log"
+    if [[ "$STRICT_BEHAVIOR_CHECK" == "1" ]]; then
+        log_info "Strict behavior check: enabled"
+    fi
+    echo -e "${BOLD}════════════════════════════════════════════════════${NC}"
+    echo ""
+
+    cleanup_single_refactor() {
+        echo ""
+        log_warn "Interrupted. Killing session..."
+        kill 0 2>/dev/null || true
+        # Log current branch info
+        if [[ -n "$_DEV_BRANCH_NAME" ]]; then
+            log_info "Development was on branch: $_DEV_BRANCH_NAME"
+        fi
+        log_info "Session log: $session_dir/logs/session.log"
+        exit 130
+    }
+    trap cleanup_single_refactor SIGINT SIGTERM
+
+    _SPAWN_RESULT=""
+
+    # Branch lifecycle: create and checkout refactor branch
+    local _proj_root
+    _proj_root="$(cd "$SCRIPT_DIR/.." && pwd)"
+    local _source_branch
+    _source_branch=$(git -C "$_proj_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
+    _ORIGINAL_BRANCH="$_source_branch"
+
+    local _branch_name="${DEV_BRANCH:-refactor/${refactor_id}-$(date +%s)}"
+    if branch_create "$_proj_root" "$_branch_name" "$_source_branch"; then
+        _DEV_BRANCH_NAME="$_branch_name"
+    else
+        log_warn "Failed to create branch; running session on current branch"
+    fi
+
+    spawn_and_wait_session \
+        "$refactor_id" "$refactor_list" "$session_id" \
+        "$bootstrap_prompt" "$session_dir" 999 "$_ORIGINAL_BRANCH"
+    local session_status="$_SPAWN_RESULT"
+
+    # Merge dev branch back to original on success
+    if [[ "$session_status" == "success" && -n "$_DEV_BRANCH_NAME" ]]; then
+        if branch_merge "$_proj_root" "$_DEV_BRANCH_NAME" "$_ORIGINAL_BRANCH" "$AUTO_PUSH"; then
+            _DEV_BRANCH_NAME=""
+        else
+            log_warn "Auto-merge failed — dev branch preserved: $_DEV_BRANCH_NAME"
+        fi
+    fi
+
+    echo ""
+    if [[ "$session_status" == "success" ]]; then
+        log_success "════════════════════════════════════════════════════"
+        log_success "  $refactor_id completed successfully!"
+        log_success "════════════════════════════════════════════════════"
+    else
+        log_error "════════════════════════════════════════════════════"
+        log_error "  $refactor_id result: $session_status"
+        log_error "  Review log: $session_dir/logs/session.log"
+        log_error "════════════════════════════════════════════════════"
+    fi
+}
+
+# ============================================================
+# Main Loop: Run all refactors
+# ============================================================
+
+main() {
+    local refactor_list="${1:-refactor-list.json}"
+
+    if [[ ! "$refactor_list" = /* ]]; then
+        refactor_list="$(pwd)/$refactor_list"
+    fi
+    REFACTOR_LIST="$refactor_list"
+
+    if [[ ! -f "$refactor_list" ]]; then
+        log_error "Refactor list not found: $refactor_list"
+        log_info "Create a refactor list first using the refactor-planner skill,"
+        log_info "or provide a path: ./run-refactor.sh run <path-to-refactor-list.json>"
+        exit 1
+    fi
+
+    check_dependencies
+    run_log_cleanup
+
+    # Initialize pipeline state if needed
+    if [[ ! -f "$STATE_DIR/pipeline.json" ]]; then
+        log_info "Initializing refactor pipeline state..."
+        local init_result
+        init_result=$(python3 "$SCRIPTS_DIR/init-refactor-pipeline.py" \
+            --refactor-list "$refactor_list" \
+            --state-dir "$STATE_DIR" 2>&1)
+
+        local init_valid
+        init_valid=$(echo "$init_result" | python3 -c "import sys,json; print(json.load(sys.stdin).get('valid', False))" 2>/dev/null || echo "False")
+
+        if [[ "$init_valid" != "True" ]]; then
+            log_error "Refactor pipeline initialization failed:"
+            echo "$init_result"
+            exit 1
+        fi
+
+        local refactors_count
+        refactors_count=$(echo "$init_result" | python3 -c "import sys,json; print(json.load(sys.stdin).get('refactors_count', 0))" 2>/dev/null || echo "0")
+        log_success "Refactor pipeline initialized with $refactors_count refactors"
+
+        # Ensure state directory is gitignored
+        local _gitignore_path
+        _gitignore_path="$(cd "$SCRIPT_DIR/.." && pwd)/.gitignore"
+        local _state_rel
+        _state_rel=$(python3 -c "import os; print(os.path.relpath('$STATE_DIR', '$(cd "$SCRIPT_DIR/.." && pwd)'))" 2>/dev/null || echo "dev-pipeline/refactor-state")
+        if [[ -f "$_gitignore_path" ]]; then
+            if ! grep -qF "$_state_rel" "$_gitignore_path" 2>/dev/null; then
+                printf '\n# Pipeline runtime state (auto-added by dev-pipeline)\n%s/\n' "$_state_rel" >> "$_gitignore_path"
+            fi
+        else
+            printf '# Pipeline runtime state (auto-added by dev-pipeline)\n%s/\n' "$_state_rel" > "$_gitignore_path"
+        fi
+    else
+        log_info "Resuming existing refactor pipeline..."
+    fi
+
+    # Print header
+    echo ""
+    echo -e "${BOLD}════════════════════════════════════════════════════${NC}"
+    echo -e "${BOLD}        Refactor Pipeline Runner Started${NC}"
+    echo -e "${BOLD}════════════════════════════════════════════════════${NC}"
+    log_info "Refactor list: $refactor_list"
+    log_info "Max retries per refactor: $MAX_RETRIES"
+    if [[ $SESSION_TIMEOUT -gt 0 ]]; then
+        log_info "Session timeout: ${SESSION_TIMEOUT}s"
+    else
+        log_info "Session timeout: none"
+    fi
+    log_info "AI CLI: $CLI_CMD (platform: $PLATFORM)"
+    if [[ -n "${MODEL:-}" ]]; then
+        log_info "Default Model: $MODEL"
+    fi
+    if [[ "$STRICT_BEHAVIOR_CHECK" == "1" ]]; then
+        log_info "Strict behavior check: enabled"
+    else
+        log_info "Strict behavior check: disabled"
+    fi
+    echo -e "${BOLD}════════════════════════════════════════════════════${NC}"
+    echo ""
+
+    # Branch lifecycle: create refactor branch for this pipeline run
+    local _proj_root
+    _proj_root="$(cd "$SCRIPT_DIR/.." && pwd)"
+    local _source_branch
+    _source_branch=$(git -C "$_proj_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
+    _ORIGINAL_BRANCH="$_source_branch"
+
+    local run_id_for_branch
+    run_id_for_branch=$(jq -r '.run_id' "$STATE_DIR/pipeline.json" 2>/dev/null || echo "$$")
+    local _branch_name="${DEV_BRANCH:-refactor/pipeline-${run_id_for_branch}}"
+    if branch_create "$_proj_root" "$_branch_name" "$_source_branch"; then
+        _DEV_BRANCH_NAME="$_branch_name"
+        log_info "Dev branch: $_branch_name"
+    else
+        log_warn "Failed to create refactor branch; running on current branch: $_source_branch"
+    fi
+
+    local session_count=0
+    local total_subagent_calls=0
+
+    while true; do
+        # Find next refactor to process (dependency-topological order)
+        local next_refactor
+        next_refactor=$(python3 "$SCRIPTS_DIR/update-refactor-status.py" \
+            --refactor-list "$refactor_list" \
+            --state-dir "$STATE_DIR" \
+            --max-retries "$MAX_RETRIES" \
+            --action get_next 2>/dev/null) || true
+
+        if [[ "$next_refactor" == "PIPELINE_COMPLETE" ]]; then
+            echo ""
+            log_success "════════════════════════════════════════════════════"
+            log_success "  All refactors processed! Refactor pipeline finished."
+            log_success "  Total sessions: $session_count"
+            log_success "  Total subagent calls: $total_subagent_calls"
+            log_success "════════════════════════════════════════════════════"
+
+            # Merge dev branch back to original
+            if [[ -n "$_DEV_BRANCH_NAME" ]]; then
+                if branch_merge "$_proj_root" "$_DEV_BRANCH_NAME" "$_ORIGINAL_BRANCH" "$AUTO_PUSH"; then
+                    _DEV_BRANCH_NAME=""
+                else
+                    log_warn "Auto-merge failed — dev branch preserved: $_DEV_BRANCH_NAME"
+                    log_warn "Merge manually: git checkout $_ORIGINAL_BRANCH && git rebase $_DEV_BRANCH_NAME"
+                fi
+            fi
+            break
+        fi
+
+        if [[ "$next_refactor" == "PIPELINE_BLOCKED" ]]; then
+            log_warn "All remaining refactors are blocked (needs_info/failed)."
+            log_warn "Run './run-refactor.sh status' to see details."
+            log_warn "Waiting 60s before re-checking... (Ctrl+C to stop)"
+            sleep 60
+            continue
+        fi
+
+        # Parse refactor info
+        local refactor_id refactor_title refactor_complexity retry_count resume_phase
+        refactor_id=$(echo "$next_refactor" | jq -r '.refactor_id')
+        refactor_title=$(echo "$next_refactor" | jq -r '.title')
+        refactor_complexity=$(echo "$next_refactor" | jq -r '.complexity')
+        retry_count=$(echo "$next_refactor" | jq -r '.retry_count // 0')
+        resume_phase=$(echo "$next_refactor" | jq -r '.resume_from_phase // "null"')
+
+        echo ""
+        echo -e "${BOLD}────────────────────────────────────────────────────${NC}"
+        log_info "Refactor: ${BOLD}$refactor_id${NC} — $refactor_title"
+        log_info "Complexity: $refactor_complexity | Retry: $retry_count / $MAX_RETRIES"
+        if [[ "$resume_phase" != "null" ]]; then
+            log_info "Resuming from Phase $resume_phase"
+        fi
+        echo -e "${BOLD}────────────────────────────────────────────────────${NC}"
+
+        # Generate session
+        local session_id run_id
+        run_id=$(jq -r '.run_id' "$STATE_DIR/pipeline.json")
+        session_id="${refactor_id}-$(date +%Y%m%d%H%M%S)"
+
+        local session_dir="$STATE_DIR/refactors/$refactor_id/sessions/$session_id"
+        mkdir -p "$session_dir/logs"
+
+        local bootstrap_prompt="$session_dir/bootstrap-prompt.md"
+        python3 "$SCRIPTS_DIR/generate-refactor-prompt.py" \
+            --refactor-list "$refactor_list" \
+            --refactor-id "$refactor_id" \
+            --session-id "$session_id" \
+            --run-id "$run_id" \
+            --retry-count "$retry_count" \
+            --resume-phase "$resume_phase" \
+            --state-dir "$STATE_DIR" \
+            --output "$bootstrap_prompt" >/dev/null 2>&1
+
+        # Log agent configuration (refactor always uses dual-agent: Orchestrator + Dev + Reviewer)
+        log_info "Pipeline mode: ${BOLD}standard${NC} (Dual Agent — Orchestrator + Dev + Reviewer)"
+        log_info "Agents: 3 (critic: disabled)"
+
+        # Spawn session
+        log_info "Spawning AI CLI session: $session_id"
+        _SPAWN_RESULT=""
+
+        spawn_and_wait_session \
+            "$refactor_id" "$refactor_list" "$session_id" \
+            "$bootstrap_prompt" "$session_dir" "$MAX_RETRIES" "$_ORIGINAL_BRANCH"
+
+        session_count=$((session_count + 1))
+        total_subagent_calls=$((total_subagent_calls + _SUBAGENT_COUNT))
+
+        log_info "Pausing 5s before next refactor..."
+        sleep 5
+    done
+}
+
+# ============================================================
+# Entry Point
+# ============================================================
+
+show_help() {
+    echo "Usage: $0 <command> [options]"
+    echo ""
+    echo "Commands:"
+    echo "  run [refactor-list.json]                Run all refactors in dependency-topological order"
+    echo "  run <refactor-id> [options]              Run a single refactor"
+    echo "  status [refactor-list.json]              Show refactor pipeline status"
+    echo "  reset                                    Clear all refactor state"
+    echo "  help                                     Show this help message"
+    echo ""
+    echo "Single Refactor Options (run <refactor-id>):"
+    echo "  --dry-run                   Generate bootstrap prompt only, don't spawn session"
+    echo "  --timeout N                 Session timeout in seconds (default: 0 = no limit)"
+    echo ""
+    echo "Environment Variables:"
+    echo "  MAX_RETRIES              Max retries per refactor (default: 3)"
+    echo "  SESSION_TIMEOUT          Session timeout in seconds (default: 0 = no limit)"
+    echo "  AI_CLI                   AI CLI command name (auto-detected: cbc or claude)"
+    echo "  VERBOSE                  Set to 1 for verbose AI CLI output"
+    echo "  STRICT_BEHAVIOR_CHECK    Force full test suite after each refactor (default: 1)"
+    echo "  HEARTBEAT_INTERVAL       Heartbeat log interval in seconds (default: 30)"
+    echo "  LOG_CLEANUP_ENABLED      Run log cleanup before execution (default: 1)"
+    echo "  LOG_RETENTION_DAYS       Delete logs older than N days (default: 14)"
+    echo "  LOG_MAX_TOTAL_MB         Keep total logs under N MB (default: 1024)"
+    echo ""
+    echo "Examples:"
+    echo "  ./run-refactor.sh run                                    # Run all refactors"
+    echo "  ./run-refactor.sh run refactor-list.json                 # Custom refactor list"
+    echo "  ./run-refactor.sh run R-001 --dry-run                    # Inspect generated prompt"
+    echo "  ./run-refactor.sh run R-001 --timeout 3600               # 1h timeout"
+    echo "  ./run-refactor.sh status                                 # Show status"
+    echo "  STRICT_BEHAVIOR_CHECK=0 ./run-refactor.sh run            # Skip full test suite"
+    echo "  MAX_RETRIES=5 ./run-refactor.sh run                      # Custom retries"
+}
+
+case "${1:-run}" in
+    run|resume)
+        shift || true
+        if [[ "${1:-}" =~ ^[Rr]-[0-9]+ ]]; then
+            run_one "$@"
+        else
+            main "${1:-refactor-list.json}"
+        fi
+        ;;
+    status)
+        check_dependencies
+        if [[ ! -f "$STATE_DIR/pipeline.json" ]]; then
+            log_error "No refactor pipeline state found. Run './run-refactor.sh run' first."
+            exit 1
+        fi
+        python3 "$SCRIPTS_DIR/update-refactor-status.py" \
+            --refactor-list "${2:-refactor-list.json}" \
+            --state-dir "$STATE_DIR" \
+            --action status
+        ;;
+    reset)
+        log_warn "Resetting refactor pipeline state..."
+        rm -rf "$STATE_DIR"
+        log_success "Refactor state cleared. Run './run-refactor.sh run' to start fresh."
+        ;;
+    help|--help|-h)
+        show_help
+        ;;
+    *)
+        log_error "Unknown command: $1"
+        show_help
+        exit 1
+        ;;
+esac