docs(track): result_migration_review_pass decisions for src/gui_2.py UNCLEAR (12 compliant + 1 migration-target)

docs/reports/RESULT_MIGRATION_REVIEW_PASS_20260617.md

@@ -0,0 +1,153 @@
+# Result Migration Sub-Track 1: Review Pass Report
+
+**Track:** `result_migration_review_pass_20260617`
+**Umbrella:** [`result_migration_20260616`](../../tracks/result_migration_20260616/spec.md)
+**Type:** audit + documentation (informational; no production code change)
+**Status:** active
+**Date:** 2026-06-17
+
+---
+
+## 0. Executive Summary
+
+This report captures the per-site decisions for the **43 ambiguous exception-handling sites** identified by `scripts/audit_exception_handling.py --json` on 2026-06-17:
+
+- **24 UNCLEAR** sites (the script cannot classify from AST alone)
+- **19 INTERNAL_RETHROW** sites (`try/except + raise`; needs the 3 legitimate pattern checks)
+
+Each site was reviewed by reading the snippet + 2-3 lines of context. The decisions flow into the umbrella's sub-tracks 2-4 as their starting migration scope.
+
+---
+
+## 1. Pre-Review Audit Snapshot (2026-06-17, base commit `b6caca40`)
+
+| Bucket | Count | Description |
+|---|---|---|
+| `UNCLEAR` | 24 | Script could not classify; needs human review |
+| `INTERNAL_RETHROW` | 19 | `try/except + raise`; needs 3-pattern check |
+| **Total review scope** | **43** | 11 files affected |
+
+Other audit findings (unchanged by this review pass):
+- 211 violations (broad catch, silent swallow, Optional[T] return) — out of scope here
+- 80 compliant sites — out of scope here
+- 25 INTERNAL_PROGRAMMER_RAISE (raise in __init__ / assert) — compliant; out of scope
+
+---
+
+## 2. Per-Site Decision Table
+
+### 2.1 `src/gui_2.py` — UNCLEAR sites (13)
+
+| Line | Context | Snippet | Decision | Pattern / Rationale |
+|---|---|---|---|---|
+| 65 | `_resolve` (deferred importer) | `except AttributeError: ... _FiledialogStub()` | **compliant** | Graceful degradation for missing optional modules (filedialog stub) |
+| 69 | `_resolve` (deferred importer) | `except (ImportError, ModuleNotFoundError): _FiledialogStub()` | **compliant** | Graceful degradation for missing optional modules (filedialog stub) |
+| 684 | `run` (ImGui main loop) | `except RuntimeError as _immapp_exc: ... log + keep alive` | **compliant** | Defer-not-catch for native bundle crashes (per workflow.md); logs to `_gui_degraded_reason` |
+| 806 | `_get_active_capabilities` | `except KeyError: caps = VendorCapabilities(... notes="unregistered")` | **compliant** | Lookup-miss-with-default for `get_capabilities(provider, model)` |
+| 1349 | `_populate_auto_slices` | `except Exception: return` | **migration-target** | Broad `except Exception` + silent return. Should narrow to `(OSError, UnicodeDecodeError)` or return `Result`. **Sub-track 4 (gui_2)** |
+| 2401 | `render_rag_panel` (vector store provider combo) | `except (ValueError, AttributeError): idx = 0` | **compliant** | `list.index` miss with default; standard Python combo-box idiom |
+| 2411 | `render_rag_panel` (embedding provider combo) | `except (ValueError, AttributeError): idx_e = 0` | **compliant** | `list.index` miss with default; standard Python combo-box idiom |
+| 2533 | `render_agent_tools_panel` (tool preset combo) | `except ValueError: idx = 0` | **compliant** | `list.index` miss with default; standard Python combo-box idiom |
+| 2561 | `render_agent_tools_panel` (filter category combo) | `except ValueError: f_idx = 0` | **compliant** | `list.index` miss with default; standard Python combo-box idiom |
+| 2759 | `render_persona_selector_panel` (load persona context preset) | `except KeyError as e: app.ai_status = f"persona context preset missing: {e}"` | **compliant** | Lookup-miss-with-user-feedback; defensive but user-visible |
+| 4106 | `render_context_files_table` (view mode combo) | `except ValueError: current_idx = 1; f_item.view_mode = "summary"` | **compliant** | `list.index` miss with default + state correction |
+| 4159 | `render_context_presets` (context preset combo) | `except ValueError: idx = 0` | **compliant** | `list.index` miss with default; standard Python combo-box idiom |
+| 6830 | `render_tier_stream_panel` (ImGui child end guard) | `except (TypeError, AttributeError): imgui.end_child()` | **compliant** | ImGui scope cleanup guard; ensures `end_child()` is always called |
+
+**Subtotals:** 12 compliant + 1 migration-target.
+
+**New heuristics identified for the audit script (added in Task 4.1):**
+1. `list.index` with `ValueError` fallback to a default index → `INTERNAL_COMPLIANT`
+2. `dict.get` / `KeyError` lookup with default value construction → `INTERNAL_COMPLIANT`
+3. Narrow `except (RuntimeError, OSError, AttributeError, ImportError)` + `imgui.end_*` or stub construction → `INTERNAL_COMPLIANT` (defer-not-catch for ImGui)
+4. Narrow `except (ImportError, ModuleNotFoundError, AttributeError)` + fallback attribute/stub → `INTERNAL_COMPLIANT` (graceful degradation)
+
+---
+
+### 2.2 `src/mcp_client.py` — UNCLEAR sites (4, baseline)
+
+*(filled in Task 2.2)*
+
+---
+
+### 2.3 `src/ai_client.py` — UNCLEAR sites (2, baseline)
+
+*(filled in Task 2.3)*
+
+---
+
+### 2.4 `src/app_controller.py` — UNCLEAR sites (2)
+
+*(filled in Task 2.4)*
+
+---
+
+### 2.5 `src/models.py` — UNCLEAR sites (2)
+
+*(filled in Task 2.5)*
+
+---
+
+### 2.6 `src/multi_agent_conductor.py` — UNCLEAR sites (1)
+
+*(filled in Task 2.6)*
+
+---
+
+### 2.7 `src/ai_client.py` — INTERNAL_RETHROW sites (6, baseline)
+
+*(filled in Task 3.1)*
+
+---
+
+### 2.8 `src/rag_engine.py` — INTERNAL_RETHROW sites (4, baseline)
+
+*(filled in Task 3.2)*
+
+---
+
+### 2.9 `src/app_controller.py` — INTERNAL_RETHROW sites (3)
+
+*(filled in Task 3.3)*
+
+---
+
+### 2.10 `src/gui_2.py` — INTERNAL_RETHROW sites (2)
+
+*(filled in Task 3.4)*
+
+---
+
+### 2.11 `src/api_hooks.py` — INTERNAL_RETHROW sites (2)
+
+*(filled in Task 3.5)*
+
+---
+
+### 2.12 `src/models.py` — INTERNAL_RETHROW site (1)
+
+*(filled in Task 3.6)*
+
+---
+
+### 2.13 `src/warmup.py` — INTERNAL_RETHROW site (1)
+
+*(filled in Task 3.7)*
+
+---
+
+## 3. Post-Review Migration Scope
+
+*(filled in Task 5.1)*
+
+---
+
+## 4. Audit Script Heuristic Updates
+
+*(filled in Task 4.1)*
+
+---
+
+## 5. Verification
+
+*(filled in Phase 6)*