manual_slop/conductor/tracks/result_migration_20260616/metadata.json

{
  "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_<YYYYMMDD>",
      "result_migration_small_files_<YYYYMMDD>",
      "result_migration_app_controller_<YYYYMMDD>",
      "result_migration_gui_2_<YYYYMMDD>",
      "result_migration_baseline_cleanup_<YYYYMMDD>"
    ],
    "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_<YYYYMMDD>.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)."
  }
}