{ "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." } }