{ "track_id": "result_migration_20260616", "name": "Result Migration (Phase 2 - eliminate all bad exception handling)", "initialized": "2026-06-16", "completed_at": "2026-06-16 (umbrella planned; sub-tracks execute over time)", "owner": "tier2-tech-lead", "priority": "A", "status": "active", "type": "refactor (5 sub-tracks; each a separate TDD execution)", "scope": { "new_files": [ "conductor/tracks/result_migration_20260616/spec.md", "conductor/tracks/result_migration_20260616/plan.md", "conductor/tracks/result_migration_20260616/metadata.json" ], "sub_tracks_planned": [ "result_migration_review_pass_", "result_migration_small_files_", "result_migration_app_controller_", "result_migration_gui_2_", "result_migration_baseline_cleanup_" ], "modified_files": [], "deleted_files": [] }, "blocked_by": [ "exception_handling_audit_20260616 (shipped 2026-06-16; produced the 268-site inventory)" ], "blocks": [ "data_structure_strengthening_20260606 (parallel; uses the cleaner Result API from this phase)", "user_stated_intent: send_result -> send mass rename (user manual refactor; post-this-phase)" ], "estimated_phases": 5, "spec": "spec.md", "plan": "plan.md", "sub_tracks": [ { "id": "1: result_migration_review_pass", "scope": "32 UNCLEAR + 25 INTERNAL_RETHROW = 57 sites across 15 files", "tshirt_size": "S", "why_first": "The UNCLEAR sites are ambiguous; human review + audit script heuristic updates feed into all later sub-tracks", "files": "All 15 files with UNCLEAR or INTERNAL_RETHROW sites" }, { "id": "2: result_migration_small_files", "scope": "37 files (35 SMALL + 2 MEDIUM); 72 V+S sites", "tshirt_size": "L", "why_second": "Quick wins; doesn't depend on the orchestrator or GUI; can run in parallel with sub-tracks 3-4", "files": "api_hooks.py, project_manager.py, aggregate.py, multi_agent_conductor.py, summary_cache.py, commands.py, external_editor.py, models.py, outline_tool.py, file_cache.py, gemini_cli_adapter.py, log_registry.py, markdown_helper.py, orchestrator_pm.py, presets.py, shell_runner.py, command_palette.py, context_presets.py, diff_viewer.py, hot_reloader.py, startup_profiler.py, summarize.py, theme_2.py, tool_presets.py, workspace_manager.py, theme_models.py, paths.py, rag_data_models.py, performance_monitor.py, plus 6 more, plus session_logger.py, warmup.py" }, { "id": "3: result_migration_app_controller", "scope": "src/app_controller.py (166KB); 56 sites (35 V + 3 S + 2 ? + 16 C)", "tshirt_size": "XL", "why_dedicated": "The orchestrator touches every subsystem; high coordination with Hook API + MMA + RAG", "files": "src/app_controller.py" }, { "id": "4: result_migration_gui_2", "scope": "src/gui_2.py (260KB); 54 sites (37 V + 2 S + 13 ? + 2 C)", "tshirt_size": "XL", "why_dedicated": "Largest file in the codebase; immediate-mode UI; depends on sub-track 3 for clean API", "files": "src/gui_2.py" }, { "id": "5: result_migration_baseline_cleanup", "scope": "3 refactored files; 112 sites (77 V + 10 S + 6 ? + 19 C)", "tshirt_size": "L", "why_last": "The baseline files ARE the convention reference; the remaining 77 violations are gaps to close (parent's Path C deferred work)", "files": "src/mcp_client.py, src/ai_client.py, src/rag_engine.py" } ], "regressions_and_pre_existing_failures": [], "pre_existing_failures_fixed_by_this_track": [], "pre_existing_failures_remaining": [], "incidental_fixes_from_parent_track": [], "deferred_to_followup_tracks": [ { "id": "send_result_to_send_rename", "title": "send_result -> send Mass Rename (user's stated intent)", "description": "The user has stated intent to do a mass rename of send_result to send. The rename is mechanical (Result[T] return type is stable; only the function name changes). The user will do this manually after this phase ships.", "track_status": "user_manual_refactor" }, { "id": "data_structure_strengthening_20260606", "title": "Data Structure Strengthening (Type Aliases + NamedTuples)", "description": "Introduce 6 TypeAlias definitions in src/type_aliases.py; replace 370+ anonymous dict[str, Any] sites in 6 high-traffic files. Spec already exists; plan pending. Blocked by this phase (cleaner Result API usage makes type-alias replacement easier).", "track_status": "ready to start; blocked by this phase" }, { "id": "live_gui_mock_injection_20260615", "title": "Live GUI Mock Injection Infrastructure", "description": "Infrastructure for mock injection into the live_gui subprocess. Unblocks proper end-to-end live_gui + AI client tests.", "track_status": "recommended; not yet specced" }, { "id": "audit_optional_in_3_files_track", "title": "Wire 4 audit scripts into CI as --strict gates", "description": "After this phase ships, scripts/audit_exception_handling.py --strict returns 0. Wire the 4 enforcement audit scripts (audit_weak_types, audit_optional_in_3_files [referenced by error_handling.md but not yet committed], audit_main_thread_imports, audit_exception_handling) into CI as --strict gates.", "track_status": "recommended; not yet specced" } ], "verification_criteria": { "g1_review_pass_complete": "32 UNCLEAR sites reviewed; per-site decision (compliant-or-migration) recorded", "g2_rethrow_pass_complete": "25 INTERNAL_RETHROW sites classified; per-site decision (one of 3 patterns or migration) recorded", "g3_audit_heuristics_updated": "scripts/audit_exception_handling.py updated with heuristics for the most common compliant patterns", "g4_updated_audit_runs": "Re-running the audit with the updated heuristics shows the UNCLEAR count is ~0", "g5_per_subtrack_scope_updated": "The umbrella spec's per-sub-track plan is updated to reflect the post-review scope", "g6_review_pass_report_exists": "docs/reports/RESULT_MIGRATION_REVIEW_PASS_.md exists with the per-site decision table", "g7_no_test_regressions": "Full test suite: 1288 + 4 + 0 (unchanged; the review pass is informational)", "g8_atomic_commits_per_subtrack": "Each sub-track is committed in 5+ atomic commits (spec, plan, metadata, code, docs)", "g9_per_commit_git_notes": "All commits have git notes", "nf1_no_production_code_change_in_review_pass": "Sub-track 1 (review pass) is informational; no production code change", "nf2_atomic_commits": "Per-task atomic commits across the 5 sub-tracks", "nf3_per_commit_git_notes": "All commits have git notes summarizing the work" }, "estimated_effort": { "method": "Scope + T-shirt size (per conductor/workflow.md §Tier 1 Track Initialization Rules). NO day estimates. The user / Tier 2 agent decides the actual pacing.", "sub_track_1_review_pass": { "scope": "57 sites across 15 files", "tshirt_size": "S" }, "sub_track_2_small_files": { "scope": "72 V+S sites across 37 files", "tshirt_size": "L" }, "sub_track_3_app_controller": { "scope": "56 sites in 1 file (166KB)", "tshirt_size": "XL" }, "sub_track_4_gui_2": { "scope": "54 sites in 1 file (260KB)", "tshirt_size": "XL" }, "sub_track_5_baseline_cleanup": { "scope": "112 sites across 3 files", "tshirt_size": "L" }, "total": "5 sub-tracks, 268 sites across 42 files" }, "risk_register": { "R1_takes_longer_than_expected": { "likelihood": "medium", "impact": "high", "mitigation": "Track 5 (baseline cleanup) is the biggest risk; the 30+ tool functions in mcp_client.py may be bigger than expected. The plan acknowledges scope can grow; the user decides whether to split sub-tracks further." }, "R2_hot_reload_breaks": { "likelihood": "medium", "impact": "high", "mitigation": "Sub-track 4 uses the hot-reload mechanism for visual verification. The migration is done incrementally; the user verifies each change visually." }, "R3_hook_api_breaks": { "likelihood": "low", "impact": "high", "mitigation": "Sub-track 3 includes before/after verification of the Hook API (via live_gui tests). The convention's Result type is structurally compatible with the existing str/None return types if needed." }, "R4_review_pass_grows_scope": { "likelihood": "medium", "impact": "medium", "mitigation": "The review pass updates the audit's heuristics; the migration scope for sub-tracks 2-4 may grow. The plan documents the scope changes in Phase 5." }, "R5_user_reorders_subtracks": { "likelihood": "low", "impact": "low", "mitigation": "The plan recommends a sequence but the user can reorder. The sub-tracks are independent enough to swap." } }, "milestone_context": { "pre_track_state": "First fully green baseline (1288 + 4 + 0). The convention is applied to 3 of 65 src/ files (mcp_client, ai_client, rag_engine). 211 violations + 25 suspicious + 32 unclear = 268 'bad' sites across 42 files, per the exception_handling_audit_20260616 report.", "post_track_target": "All 268 sites migrated. The convention is applied to all 65 src/ files. The 4 enforcement audit scripts can be wired into CI as --strict gates. Test pass count: 1288 + 4 + 0 (unchanged; the migration is behavior-preserving).", "historical_context": "This is the migration phase that completes the data_oriented_error_handling_20260606 track (shipped 2026-06-12). The parent track established the convention; this phase applies it to the remaining 62 src/ files and closes the gaps in the 3 refactored files.", "user_intent_after_this_track": "User decides: send_result -> send mass rename (manual) or data_structure_strengthening_20260606 (parallel track; uses the cleaner Result API from this phase)." } }