{
  "track_id": "exception_handling_audit_20260616",
  "name": "Exception Handling Audit (Convention Compliance + Doc Clarification)",
  "initialized": "2026-06-16",
  "completed_at": "2026-06-16 (shipped in this session)",
  "owner": "tier2-tech-lead",
  "priority": "B",
  "status": "completed",
  "type": "audit + documentation (no production code change)",
  "scope": {
    "new_files": [
      "scripts/audit_exception_handling.py",
      "docs/reports/EXCEPTION_HANDLING_AUDIT_20260616.md"
    ],
    "modified_files": [
      "conductor/code_styleguides/error_handling.md",
      "docs/guide_app_controller.md",
      "conductor/product-guidelines.md"
    ],
    "deleted_files": []
  },
  "blocked_by": [],
  "blocks": [
    "user_stated_intent: app_controller_result_migration (recommended next track; user decides)",
    "user_stated_intent: gui_2_result_migration (recommended next track; user decides)",
    "user_stated_intent: send_result -> send mass rename (user's planned manual refactor)"
  ],
  "estimated_phases": 5,
  "spec": "spec.md",
  "plan": "plan.md",

  "audit_findings_20260616": {
    "baseline_files_refactored": [
      "src/mcp_client.py (refactored 2026-06-12; 4 _result variants; 30+ tool-function refactor deferred)",
      "src/ai_client.py (refactored 2026-06-12; ProviderError removed; send_result() public; send() @deprecated)",
      "src/rag_engine.py (refactored 2026-06-12; _init_vector_store_result; _validate_collection_dim_result)"
    ],
    "migration_target_files": [
      "src/app_controller.py (166KB; 56 sites; 35 violations + 3 suspicious + 2 unclear)",
      "src/gui_2.py (260KB; 54 sites; 37 violations + 2 suspicious + 13 unclear)",
      "src/session_logger.py (8 sites; 8 violations)",
      "src/warmup.py (7 sites; 6 violations + 1 suspicious)",
      "src/theme_models.py (10 sites; 6 violations + 2 unclear)",
      "src/api_hooks.py (5 sites; 5 violations)",
      "src/project_manager.py (5 sites; 5 violations)",
      "src/multi_agent_conductor.py",
      "src/aggregate.py",
      "src/paths.py",
      "src/history.py"
    ],
    "headline_counts": {
      "files_scanned": 65,
      "files_with_findings": 42,
      "total_sites": 348,
      "try_sites": 8,
      "except_sites": 283,
      "raise_sites": 57,
      "compliant_sites": 80,
      "suspicious_sites": 25,
      "violation_sites": 211,
      "unclear_sites": 32,
      "baseline_sites": 112,
      "baseline_violations": 77,
      "migration_target_sites": 236,
      "migration_target_violations": 134
    },
    "category_breakdown": {
      "INTERNAL_BROAD_CATCH": 147,
      "INTERNAL_SILENT_SWALLOW": 61,
      "UNCLEAR": 32,
      "INTERNAL_RETHROW": 25,
      "INTERNAL_PROGRAMMER_RAISE": 25,
      "BOUNDARY_SDK": 19,
      "INTERNAL_COMPLIANT": 16,
      "BOUNDARY_FASTAPI": 12,
      "BOUNDARY_CONVERSION": 8,
      "INTERNAL_OPTIONAL_RETURN": 3
    },
    "doc_gaps_identified": [
      "G1: FastAPI HTTPException in _api_* handlers not explicitly documented as a legitimate boundary pattern",
      "G2: The 'broad except Exception' anti-pattern doesn't distinguish between 'swallow' and 'convert to ErrorInfo'",
      "G3: The 'constructors can raise' rule is brief; needs elaboration",
      "G4: The 're-raise' pattern is not in the styleguide at all",
      "G5: The new audit script is not referenced from the styleguide"
    ],
    "doc_gaps_closed": [
      "Added 5 new sections to conductor/code_styleguides/error_handling.md",
      "Added new Exception Handling section to docs/guide_app_controller.md",
      "Added audit script cross-reference to conductor/product-guidelines.md"
    ]
  },

  "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": "app_controller_result_migration",
      "title": "app_controller.py Result Migration (Phase 2.2 of doeh spec)",
      "description": "Migrate src/app_controller.py to the Result pattern. ~199 Optional[X] sites, ~30 except Exception blocks. Per the doeh spec §12.2, this is the highest-priority migration because app_controller is the orchestrator and touches every subsystem. Recommended next track based on the audit (35 violations, 3 suspicious, 2 unclear = 40 sites).",
      "track_status": "recommended; not yet specced"
    },
    {
      "id": "gui_2_result_migration",
      "title": "gui_2.py Result Migration (lowest-priority migration per doeh spec)",
      "description": "Migrate src/gui_2.py (260KB) to the Result pattern. Largest file in the codebase; 37 violations, 2 suspicious, 13 unclear = 52 sites. Per the doeh spec §12.2, this is the lowest-priority migration. Recommended only after app_controller is done.",
      "track_status": "recommended; not yet specced"
    },
    {
      "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 track 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 both this track (cleaner Result API usage makes type-alias replacement easier) and the user's send_result -> send rename.",
      "track_status": "ready to start; blocked by this track + the send_result -> send rename"
    },
    {
      "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": "rag_test_quality_cleanup",
      "title": "RAG Test Quality Cleanup",
      "description": "Replace time.sleep(0.5) patterns in RAG tests with poll loops; improve error messages; remove flaky patterns. Not a bug fix; quality improvement.",
      "track_status": "recommended; not yet specced"
    }
  ],

  "verification_criteria": {
    "g1_script_exists": "scripts/audit_exception_handling.py exists and runs without errors",
    "g2_fastapi_classified": "All 11 HTTPException raises in app_controller.py _api_* handlers are classified as BOUNDARY_FASTAPI (not INTERNAL_RETHROW)",
    "g3_constructor_raises_classified": "All raise ValueError/TypeError/NotImplementedError in __init__ are classified as INTERNAL_PROGRAMMER_RAISE (not INTERNAL_RETHROW)",
    "g4_broad_catch_in_result_classified": "The except Exception + ErrorInfo conversion in _validate_collection_dim_result is classified as BOUNDARY_CONVERSION (not INTERNAL_BROAD_CATCH)",
    "g5_baseline_breakdown": "The report shows baseline (3 refactored files) vs migration target (~10 unrefactored files) with separate violation counts",
    "g6_styleguide_5_sections": "conductor/code_styleguides/error_handling.md has 5 new sections: Boundary Types, Broad-Except Distinction, Constructors Can Raise, Re-Raise Patterns, Audit Script",
    "g7_app_controller_doc_updated": "docs/guide_app_controller.md has a new Exception Handling section explaining the FastAPI boundary",
    "g8_product_guidelines_updated": "conductor/product-guidelines.md has the audit script cross-reference",
    "g9_audit_report_exists": "docs/reports/EXCEPTION_HANDLING_AUDIT_20260616.md exists with the per-file + per-category breakdown",
    "nf1_no_production_code_change": "No src/*.py files modified",
    "nf2_atomic_commits": "8 commits minimum (spec, plan, metadata, tracks.md, script, docs/styleguide, docs/app_controller, docs/guidelines, report, final-state)",
    "nf3_per_commit_git_notes": "All commits have git notes"
  },

  "estimated_effort": {
    "method": "Scope (per conductor/workflow.md §Tier 1 Track Initialization Rules). NO day estimates.",
    "phase_1": "5 artifacts (spec + plan + metadata + tracks.md update)",
    "phase_2": "792-line audit script + 4 verifications",
    "phase_3": "5 doc/codestyle updates + 1 product-guidelines cross-reference",
    "phase_4": "370-line audit report + metadata update",
    "phase_5": "User manual verification (the user reviews the report)",
    "total": "~800 lines of new artifacts; 9 atomic commits; all with git notes"
  },

  "risk_register": {
    "R1_audit_misclassifies": {
      "likelihood": "medium",
      "impact": "high",
      "mitigation": "The script's classification is verified against 3 known-good sites (FastAPI HTTPException, __init__ raises, broad-catch-in-result). The 1-line hints make misclassifications easy to spot."
    },
    "R2_doc_inconsistency": {
      "likelihood": "low",
      "impact": "medium",
      "mitigation": "Each new section is small (5-30 lines) and follows the existing tone. The Tier 2 implementer can request a review if a section feels off."
    },
    "R3_violation_count_misread": {
      "likelihood": "medium",
      "impact": "medium",
      "mitigation": "The report is explicit: 'These are migration-target sites, not bugs. The user decides what to migrate.'"
    },
    "R4_app_controller_doc_too_aggressive": {
      "likelihood": "low",
      "impact": "low",
      "mitigation": "The new section explicitly says 'Recommended future track: app_controller_result_migration_20260616 (not in this track's scope; the user decides)'."
    },
    "R5_script_performance": {
      "likelihood": "low",
      "impact": "low",
      "mitigation": "The script uses AST (O(n) over the source files); tested on 65 files in <2s."
    }
  },

  "milestone_context": {
    "pre_track_state": "First fully green baseline (1288 + 4 + 0) since data_oriented_error_handling_20260606 shipped 2026-06-12. The convention is applied to 3 of 65 src/ files.",
    "post_track_target": "Audit report generated; 5 doc gaps closed; 3 followup migration tracks identified (app_controller, gui_2, etc.). The codebase is at the same test pass count (1288 + 4 + 0) but now has a clear inventory of the migration target.",
    "historical_context": "This is the first AUDIT track (informational; no code change) since the nagent_review_20260608 review. It produces a report + doc updates, not a refactor.",
    "user_intent_after_this_track": "User decides: which migration-target file is the next refactor track? (app_controller? gui_2? something else?) Or proceed to send_result -> send mass rename, or data_structure_strengthening_20260606."
  }
}
