prizmkit 1.1.7 → 1.1.9

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

@@ -5,12 +5,12 @@ 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.
+# execute refactors from a .prizmkit/plans/refactor-list.json specification.
 #
 # Usage:
-#   ./run-refactor.sh run [refactor-list.json]          Run all refactors
+#   ./run-refactor.sh run [.prizmkit/plans/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 status [.prizmkit/plans/refactor-list.json]       Show pipeline status
 #   ./run-refactor.sh reset                             Clear all state
 #
 # Environment Variables:
@@ -31,7 +31,8 @@ set -euo pipefail
 # ============================================================
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-STATE_DIR="$SCRIPT_DIR/refactor-state"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+STATE_DIR="${PROJECT_ROOT}/.prizmkit/state/refactor"
 SCRIPTS_DIR="$SCRIPT_DIR/scripts"
 
 # Configuration
@@ -43,6 +44,7 @@ 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}
+MODEL=${MODEL:-""}
 DEV_BRANCH=${DEV_BRANCH:-""}
 AUTO_PUSH=${AUTO_PUSH:-0}
 STRICT_BEHAVIOR_CHECK=${STRICT_BEHAVIOR_CHECK:-1}
@@ -78,7 +80,8 @@ spawn_and_wait_session() {
     local bootstrap_prompt="$4"
     local session_dir="$5"
     local max_retries="$6"
-    local base_branch="${7:-main}"
+    local item_model="${7:-}"
+    local base_branch="${8:-main}"
 
     local session_log="$session_dir/logs/session.log"
     local progress_json="$session_dir/logs/progress.json"
@@ -96,7 +99,9 @@ spawn_and_wait_session() {
     fi
 
     local model_flag=""
-    if [[ -n "${MODEL:-}" ]]; then
+    if [[ -n "$item_model" ]]; then
+        model_flag="--model $item_model"
+    elif [[ -n "${MODEL:-}" ]]; then
         model_flag="--model $MODEL"
     fi
 
@@ -104,6 +109,9 @@ spawn_and_wait_session() {
     # within an existing Claude Code session (e.g. via launch-refactor-daemon.sh).
     unset CLAUDECODE 2>/dev/null || true
 
+    # Log bootstrap prompt in test mode
+    prizm_log_bootstrap_prompt "$bootstrap_prompt" "$refactor_id"
+
     case "$CLI_CMD" in
         *claude*)
             # Claude Code: prompt via -p, --dangerously-skip-permissions for auto-accept
@@ -226,9 +234,69 @@ spawn_and_wait_session() {
 
     log_info "Session result: $session_status"
 
+    # Validate key artifacts exist after successful session
+    if [[ "$session_status" == "success" ]]; then
+        local _artifact_root
+        _artifact_root="$(cd "$SCRIPT_DIR/.." && pwd)"
+        local plan_file="$_artifact_root/.prizmkit/refactor/$refactor_id/plan.md"
+        if [[ ! -f "$plan_file" ]]; then
+            log_warn "ARTIFACT_MISSING: plan.md not found at $plan_file"
+        fi
+
+        # Validate checkpoint completeness
+        local checkpoint_file="$_artifact_root/.prizmkit/refactor/$refactor_id/workflow-checkpoint.json"
+        if [[ -f "$checkpoint_file" ]]; then
+            local checkpoint_result
+            checkpoint_result=$(python3 -c "
+import json, sys
+try:
+    with open(sys.argv[1]) as f:
+        data = json.load(f)
+except json.JSONDecodeError as e:
+    print('CORRUPTED: {}'.format(e))
+    sys.exit(2)
+incomplete = [s for s in data['steps'] if s['status'] not in ('completed', 'skipped')]
+if incomplete:
+    for s in incomplete:
+        print('INCOMPLETE: {} {} = {}'.format(s['id'], s['skill'], s['status']))
+    sys.exit(1)
+print('ALL_COMPLETE')
+sys.exit(0)
+" "$checkpoint_file" 2>&1)
+            local check_exit=$?
+            if [[ $check_exit -eq 2 ]]; then
+                log_warn "CHECKPOINT_CORRUPTED: workflow-checkpoint.json is not valid JSON"
+            elif [[ $check_exit -eq 1 ]]; then
+                log_warn "CHECKPOINT_INCOMPLETE: Not all workflow steps completed:"
+                echo "$checkpoint_result" | while read -r line; do log_warn "  $line"; done
+            else
+                log_info "CHECKPOINT: All workflow steps completed"
+            fi
+        else
+            log_info "CHECKPOINT: No workflow-checkpoint.json found (checkpoint system not active)"
+        fi
+    fi
+
     # Subagent detection
     prizm_detect_subagents "$session_log"
 
+    # Propagate completion notes for dependency context (only on success)
+    if [[ "$session_status" == "success" ]]; then
+        local summary_path="$project_root/.prizmkit/refactor/$refactor_id/completion-summary.json"
+        if [[ -f "$summary_path" ]]; then
+            python3 "$SCRIPTS_DIR/patch-completion-notes.py" \
+                --refactor-list "$refactor_list" \
+                --refactor-id "$refactor_id" \
+                --summary "$summary_path" >/dev/null 2>&1 && {
+                log_info "Propagated completion notes for $refactor_id to refactor-list.json"
+            } || {
+                log_warn "Failed to propagate completion notes for $refactor_id"
+            }
+        else
+            log_info "No completion-summary.json for $refactor_id — dependency context will be limited"
+        fi
+    fi
+
     # Update refactor status
     python3 "$SCRIPTS_DIR/update-refactor-status.py" \
         --refactor-list "$refactor_list" \
@@ -239,7 +307,7 @@ spawn_and_wait_session() {
         --max-retries "$max_retries" \
         --action update >/dev/null 2>&1 || true
 
-    # Commit refactor-list.json status update (pipeline management commit)
+    # Commit .prizmkit/plans/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
@@ -319,11 +387,31 @@ run_one() {
     local refactor_id=""
     local refactor_list=""
     local dry_run=false
+    local do_clean=false
+    local no_reset=false
+    local mode_override=""
+    local critic_override=""
 
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --dry-run) dry_run=true; shift ;;
+            --clean) do_clean=true; shift ;;
+            --no-reset) no_reset=true; shift ;;
             --timeout) shift; SESSION_TIMEOUT="${1:-0}"; shift ;;
+            --mode)
+                shift
+                if [[ $# -eq 0 ]]; then
+                    log_error "--mode requires a value (lite|standard|full)"
+                    exit 1
+                fi
+                case "$1" in
+                    lite|standard|full) mode_override="$1" ;;
+                    *) log_error "Invalid mode: $1 (must be lite, standard, or full)"; exit 1 ;;
+                esac
+                shift
+                ;;
+            --critic) critic_override="true"; shift ;;
+            --no-critic) critic_override="false"; shift ;;
             R-*|r-*) refactor_id="$1"; shift ;;
             *) refactor_list="$1"; shift ;;
         esac
@@ -337,7 +425,7 @@ run_one() {
     fi
 
     if [[ -z "$refactor_list" ]]; then
-        refactor_list="refactor-list.json"
+        refactor_list=".prizmkit/plans/refactor-list.json"
     fi
     if [[ ! "$refactor_list" = /* ]]; then
         refactor_list="$(pwd)/$refactor_list"
@@ -366,7 +454,7 @@ run_one() {
         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")
+        _state_rel=$(python3 -c "import os; print(os.path.relpath('$STATE_DIR', '$(cd "$SCRIPT_DIR/.." && pwd)'))" 2>/dev/null || echo ".prizmkit/state/refactor")
         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"
@@ -404,12 +492,48 @@ for item in data.get('refactors', []):
 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
+    # Optional Clean
+    if [[ "$do_clean" == true ]]; then
+        if [[ "$dry_run" == true ]]; then
+            log_warn "Dry-run mode: --clean ignored (no artifacts will be deleted)"
+        else
+            log_info "Cleaning artifacts for $refactor_id..."
+
+            local project_root
+            project_root="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+            local refactor_dir="$project_root/.prizmkit/refactor/$refactor_id"
+            if [[ -d "$refactor_dir" ]]; then
+                rm -rf "$refactor_dir"
+                log_info "Removed $refactor_dir"
+            fi
+
+            local dev_team_dir="$project_root/.dev-team"
+            if [[ -d "$dev_team_dir" ]]; then
+                rm -rf "$dev_team_dir"
+                log_info "Removed $dev_team_dir"
+            fi
+
+            local refactor_state_dir="$STATE_DIR/refactors/$refactor_id"
+            if [[ -d "$refactor_state_dir" ]]; then
+                rm -rf "$refactor_state_dir"
+                log_info "Removed $refactor_state_dir"
+            fi
+        fi
+    fi
+
+    # Reset refactor status (conditional)
+    if [[ "$no_reset" == false && "$dry_run" == false ]]; then
+        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 || {
+            log_warn "Failed to reset refactor status (may already be pending)"
+        }
+    elif [[ "$dry_run" == true && "$no_reset" == false ]]; then
+        log_info "Dry-run mode: skipping status reset"
+    fi
 
     # Generate bootstrap prompt
     local run_id session_id session_dir bootstrap_prompt
@@ -420,16 +544,66 @@ sys.exit(1)
 
     bootstrap_prompt="$session_dir/bootstrap-prompt.md"
 
+    # Read retry count from status.json
+    local retry_count
+    retry_count=$(python3 -c "
+import json, os
+status_path = os.path.join('$STATE_DIR', 'refactors', '$refactor_id', 'status.json')
+if os.path.isfile(status_path):
+    with open(status_path) as f:
+        d = json.load(f)
+    print(d.get('retry_count', 0))
+else:
+    print(0)
+" 2>/dev/null || echo "0")
+    local resume_phase
+    resume_phase=$(python3 -c "
+import json, os
+status_path = os.path.join('$STATE_DIR', 'refactors', '$refactor_id', 'status.json')
+if os.path.isfile(status_path):
+    with open(status_path) as f:
+        d = json.load(f)
+    print(d.get('resume_from_phase') or 'null')
+else:
+    print('null')
+" 2>/dev/null || echo "null")
+
     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
+    local prompt_args=(
+        --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"
+    )
+
+    if [[ -n "$mode_override" ]]; then
+        prompt_args+=(--mode "$mode_override")
+    elif [[ -n "${PIPELINE_MODE:-}" ]]; then
+        prompt_args+=(--mode "$PIPELINE_MODE")
+    fi
+
+    if [[ -n "${critic_override:-}" ]]; then
+        prompt_args+=(--critic "$critic_override")
+    elif [[ "${ENABLE_CRITIC:-}" == "true" || "${ENABLE_CRITIC:-}" == "1" ]]; then
+        prompt_args+=(--critic "true")
+    elif [[ "${ENABLE_CRITIC:-}" == "false" || "${ENABLE_CRITIC:-}" == "0" ]]; then
+        prompt_args+=(--critic "false")
+    fi
+
+    local gen_output
+    gen_output=$(python3 "$SCRIPTS_DIR/generate-refactor-prompt.py" "${prompt_args[@]}" 2>/dev/null) || {
+        log_error "Failed to generate bootstrap prompt for $refactor_id"
+        return 1
+    }
+    local refactor_model pipeline_mode agent_count critic_enabled
+    refactor_model=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('model',''))" 2>/dev/null || echo "")
+    pipeline_mode=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('pipeline_mode','standard'))" 2>/dev/null || echo "standard")
+    agent_count=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('agent_count',3))" 2>/dev/null || echo "3")
+    critic_enabled=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('critic_enabled','false'))" 2>/dev/null || echo "false")
 
     if [[ "$dry_run" == true ]]; then
         echo ""
@@ -438,6 +612,20 @@ sys.exit(1)
         echo -e "${BOLD}  Complexity: $refactor_complexity${NC}"
         echo -e "${BOLD}════════════════════════════════════════════════════${NC}"
         echo ""
+        log_info "Session ID:    $session_id"
+        if [[ -n "$mode_override" ]]; then
+            log_info "Mode Override: $mode_override"
+        fi
+        log_info "Pipeline mode: $pipeline_mode"
+        log_info "Agents:        $agent_count (critic: $([ "$critic_enabled" = "true" ] && echo "enabled" || echo "disabled"))"
+        if [[ -n "$refactor_model" ]]; then
+            log_info "Refactor Model: $refactor_model"
+        elif [[ -n "$MODEL" ]]; then
+            log_info "Model (env):    $MODEL"
+        else
+            log_info "Model:          (CLI default)"
+        fi
+        echo ""
         log_info "Bootstrap prompt written to:"
         echo "  $bootstrap_prompt"
         echo ""
@@ -454,6 +642,18 @@ sys.exit(1)
     log_info "Session ID: $session_id"
     log_info "Prompt: $bootstrap_prompt"
     log_info "Log: $session_dir/logs/session.log"
+    local _run_one_mode_desc
+    case "$pipeline_mode" in
+        lite)     _run_one_mode_desc="Tier 1 — Single Agent" ;;
+        standard) _run_one_mode_desc="Tier 2 — Orchestrator + Dev + Reviewer" ;;
+        full)     _run_one_mode_desc="Tier 3 — Full Team (+ Multi-Critic)" ;;
+        *)        _run_one_mode_desc="$pipeline_mode" ;;
+    esac
+    log_info "Pipeline mode: ${BOLD}$pipeline_mode${NC} ($_run_one_mode_desc)"
+    log_info "Agents: $agent_count (critic: $([ "$critic_enabled" = "true" ] && echo "enabled" || echo "disabled"))"
+    if [[ -n "$refactor_model" ]]; then
+        log_info "Refactor model: $refactor_model"
+    fi
     if [[ "$STRICT_BEHAVIOR_CHECK" == "1" ]]; then
         log_info "Strict behavior check: enabled"
     fi
@@ -491,7 +691,7 @@ sys.exit(1)
 
     spawn_and_wait_session \
         "$refactor_id" "$refactor_list" "$session_id" \
-        "$bootstrap_prompt" "$session_dir" 999 "$_ORIGINAL_BRANCH"
+        "$bootstrap_prompt" "$session_dir" 999 "$refactor_model" "$_ORIGINAL_BRANCH"
     local session_status="$_SPAWN_RESULT"
 
     # Merge dev branch back to original on success
@@ -521,7 +721,7 @@ sys.exit(1)
 # ============================================================
 
 main() {
-    local refactor_list="${1:-refactor-list.json}"
+    local refactor_list="${1:-.prizmkit/plans/refactor-list.json}"
 
     if [[ ! "$refactor_list" = /* ]]; then
         refactor_list="$(pwd)/$refactor_list"
@@ -531,7 +731,7 @@ main() {
     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>"
+        log_info "or provide a path: ./run-refactor.sh run <path-to-.prizmkit/plans/refactor-list.json>"
         exit 1
     fi
 
@@ -563,7 +763,7 @@ main() {
         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")
+        _state_rel=$(python3 -c "import os; print(os.path.relpath('$STATE_DIR', '$(cd "$SCRIPT_DIR/.." && pwd)'))" 2>/dev/null || echo ".prizmkit/state/refactor")
         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"
@@ -599,23 +799,13 @@ main() {
     echo -e "${BOLD}════════════════════════════════════════════════════${NC}"
     echo ""
 
-    # Branch lifecycle: create refactor branch for this pipeline run
+    # Branch lifecycle: per-refactor branches (like feature pipeline)
     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
 
@@ -639,20 +829,11 @@ main() {
             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 "All remaining refactors are blocked (failed/dependency unmet)."
             log_warn "Run './run-refactor.sh status' to see details."
             log_warn "Waiting 60s before re-checking... (Ctrl+C to stop)"
             sleep 60
@@ -676,6 +857,23 @@ main() {
         fi
         echo -e "${BOLD}────────────────────────────────────────────────────${NC}"
 
+        # Pre-commit any dirty tree from previous iteration
+        if ! git -C "$_proj_root" diff --quiet HEAD 2>/dev/null || [ -n "$(git -C "$_proj_root" ls-files --others --exclude-standard 2>/dev/null)" ]; then
+            log_info "Dirty working tree detected — committing before $refactor_id..."
+            git -C "$_proj_root" add -A 2>/dev/null || true
+            git -C "$_proj_root" commit --no-verify -m "chore: capture artifacts before $refactor_id session" 2>/dev/null || true
+        fi
+
+        # Create per-refactor dev branch
+        local _refactor_branch="${DEV_BRANCH:-refactor/${refactor_id}-$(date +%Y%m%d%H%M)}"
+        if branch_create "$_proj_root" "$_refactor_branch" "$_ORIGINAL_BRANCH"; then
+            _DEV_BRANCH_NAME="$_refactor_branch"
+            log_info "Dev branch: $_refactor_branch"
+        else
+            log_warn "Failed to create dev branch; running on current branch: $_ORIGINAL_BRANCH"
+            _DEV_BRANCH_NAME=""
+        fi
+
         # Generate session
         local session_id run_id
         run_id=$(jq -r '.run_id' "$STATE_DIR/pipeline.json")
@@ -685,19 +883,62 @@ main() {
         mkdir -p "$session_dir/logs"
 
         local bootstrap_prompt="$session_dir/bootstrap-prompt.md"
-        python3 "$SCRIPTS_DIR/generate-refactor-prompt.py" \
+
+        local main_prompt_args=(
+            --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"
+        )
+
+        # Support PIPELINE_MODE env var (set by launch-refactor-daemon.sh --mode)
+        if [[ -n "${PIPELINE_MODE:-}" ]]; then
+            main_prompt_args+=(--mode "$PIPELINE_MODE")
+        fi
+
+        # Support ENABLE_CRITIC env var (set by launch-refactor-daemon.sh --critic)
+        if [[ "${ENABLE_CRITIC:-}" == "true" || "${ENABLE_CRITIC:-}" == "1" ]]; then
+            main_prompt_args+=(--critic "true")
+        elif [[ "${ENABLE_CRITIC:-}" == "false" || "${ENABLE_CRITIC:-}" == "0" ]]; then
+            main_prompt_args+=(--critic "false")
+        fi
+
+        local gen_output
+        gen_output=$(python3 "$SCRIPTS_DIR/generate-refactor-prompt.py" "${main_prompt_args[@]}" 2>/dev/null) || {
+            log_error "Failed to generate bootstrap prompt for $refactor_id"
+            continue
+        }
+        local refactor_model pipeline_mode agent_count critic_enabled
+        refactor_model=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('model',''))" 2>/dev/null || echo "")
+        pipeline_mode=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('pipeline_mode','standard'))" 2>/dev/null || echo "standard")
+        agent_count=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('agent_count',3))" 2>/dev/null || echo "3")
+        critic_enabled=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('critic_enabled','false'))" 2>/dev/null || echo "false")
+
+        # Log pipeline mode and agent configuration
+        local _mode_desc
+        case "$pipeline_mode" in
+            lite)     _mode_desc="Tier 1 — Single Agent" ;;
+            standard) _mode_desc="Tier 2 — Orchestrator + Dev + Reviewer" ;;
+            full)     _mode_desc="Tier 3 — Full Team (+ Multi-Critic)" ;;
+            *)        _mode_desc="$pipeline_mode" ;;
+        esac
+        log_info "Pipeline mode: ${BOLD}$pipeline_mode${NC} ($_mode_desc)"
+        log_info "Agents: $agent_count (critic: $([ "$critic_enabled" = "true" ] && echo "enabled" || echo "disabled"))"
+
+        if [[ -n "$refactor_model" ]]; then
+            log_info "Refactor model: $refactor_model"
+        fi
+
+        # Mark refactor as in-progress before spawning session
+        python3 "$SCRIPTS_DIR/update-refactor-status.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)"
+            --refactor-id "$refactor_id" \
+            --action start >/dev/null 2>&1 || true
 
         # Spawn session
         log_info "Spawning AI CLI session: $session_id"
@@ -705,7 +946,50 @@ main() {
 
         spawn_and_wait_session \
             "$refactor_id" "$refactor_list" "$session_id" \
-            "$bootstrap_prompt" "$session_dir" "$MAX_RETRIES" "$_ORIGINAL_BRANCH"
+            "$bootstrap_prompt" "$session_dir" "$MAX_RETRIES" "$refactor_model" "$_ORIGINAL_BRANCH"
+
+        # Validate key artifacts after successful session
+        if [[ "$_SPAWN_RESULT" == "success" ]]; then
+            local _artifact_root
+            _artifact_root="$(cd "$SCRIPT_DIR/.." && pwd)"
+            local plan_file="$_artifact_root/.prizmkit/refactor/$refactor_id/plan.md"
+            if [[ ! -f "$plan_file" ]]; then
+                log_warn "ARTIFACT_MISSING: plan.md not found at $plan_file"
+            else
+                log_info "ARTIFACT_CHECK: plan.md exists for $refactor_id"
+            fi
+        fi
+
+        local session_status="$_SPAWN_RESULT"
+
+        # Merge per-refactor 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"
+                log_warn "Merge manually: git checkout $_ORIGINAL_BRANCH && git rebase $_DEV_BRANCH_NAME"
+                git -C "$_proj_root" checkout "$_ORIGINAL_BRANCH" 2>/dev/null || true
+                _DEV_BRANCH_NAME=""
+            fi
+        elif [[ -n "$_DEV_BRANCH_NAME" ]]; then
+            # Session failed — return to original branch, preserve dev branch for inspection
+            if ! git -C "$_proj_root" checkout "$_ORIGINAL_BRANCH" 2>/dev/null; then
+                log_warn "Failed to checkout $_ORIGINAL_BRANCH after session failure — staying on dev branch"
+            fi
+            log_warn "Session failed — dev branch preserved for inspection: $_DEV_BRANCH_NAME"
+            _DEV_BRANCH_NAME=""
+        fi
+
+        # Stuck detection
+        if python3 "$SCRIPTS_DIR/detect-stuck.py" \
+            --state-dir "$STATE_DIR" \
+            --pipeline-type refactor \
+            --refactor-list "$REFACTOR_LIST" \
+            --max-retries "$MAX_RETRIES" \
+            2>/dev/null | jq -e '.stuck_count > 0' >/dev/null 2>&1; then
+            log_warn "STUCK_DETECTED: Some refactors may be stuck — run detect-stuck.py for details"
+        fi
 
         session_count=$((session_count + 1))
         total_subagent_calls=$((total_subagent_calls + _SUBAGENT_COUNT))
@@ -723,19 +1007,27 @@ show_help() {
     echo "Usage: $0 <command> [options]"
     echo ""
     echo "Commands:"
-    echo "  run [refactor-list.json]                Run all refactors in dependency-topological order"
+    echo "  run [.prizmkit/plans/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 "  status [.prizmkit/plans/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 "  --clean                     Delete artifacts and reset before running"
+    echo "  --no-reset                  Skip status reset (preserve retry count)"
     echo "  --timeout N                 Session timeout in seconds (default: 0 = no limit)"
+    echo "  --mode <lite|standard|full> Override pipeline mode"
+    echo "  --critic                    Enable adversarial critic review"
+    echo "  --no-critic                 Disable adversarial critic review"
     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 "  MODEL                    Default AI model (overridden by per-refactor model in refactor list)"
+    echo "  PIPELINE_MODE            Default pipeline mode: lite|standard|full (overridden by --mode)"
+    echo "  ENABLE_CRITIC            Enable/disable critic: true|false|1|0 (overridden by --critic/--no-critic)"
     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)"
@@ -746,7 +1038,7 @@ show_help() {
     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 .prizmkit/plans/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"
@@ -760,7 +1052,7 @@ case "${1:-run}" in
         if [[ "${1:-}" =~ ^[Rr]-[0-9]+ ]]; then
             run_one "$@"
         else
-            main "${1:-refactor-list.json}"
+            main "${1:-.prizmkit/plans/refactor-list.json}"
         fi
         ;;
     status)
@@ -770,7 +1062,7 @@ case "${1:-run}" in
             exit 1
         fi
         python3 "$SCRIPTS_DIR/update-refactor-status.py" \
-            --refactor-list "${2:-refactor-list.json}" \
+            --refactor-list "${2:-.prizmkit/plans/refactor-list.json}" \
             --state-dir "$STATE_DIR" \
             --action status
         ;;
@@ -779,6 +1071,40 @@ case "${1:-run}" in
         rm -rf "$STATE_DIR"
         log_success "Refactor state cleared. Run './run-refactor.sh run' to start fresh."
         ;;
+    unskip)
+        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
+        _unskip_refactor_list=".prizmkit/plans/refactor-list.json"
+        _unskip_refactor_id=""
+        shift || true
+        # Parse arguments: optional refactor-id and refactor-list path
+        while [[ $# -gt 0 ]]; do
+            if [[ "$1" =~ ^[Rr]-[0-9]+ ]]; then
+                _unskip_refactor_id="$1"
+            else
+                _unskip_refactor_list="$1"
+            fi
+            shift
+        done
+        _unskip_args=(
+            --refactor-list "$_unskip_refactor_list"
+            --state-dir "$STATE_DIR"
+            --action unskip
+        )
+        if [[ -n "$_unskip_refactor_id" ]]; then
+            _unskip_args+=(--refactor-id "$_unskip_refactor_id")
+        fi
+        python3 "$SCRIPTS_DIR/update-refactor-status.py" "${_unskip_args[@]}"
+
+        # Commit the status change
+        if ! git diff --quiet "$_unskip_refactor_list" 2>/dev/null; then
+            git add "$_unskip_refactor_list"
+            git commit -m "chore: unskip auto-skipped refactors" 2>/dev/null || true
+        fi
+        ;;
     help|--help|-h)
         show_help
         ;;