diff --git a/conductor/tracks/exception_handling_audit_20260616/metadata.json b/conductor/tracks/exception_handling_audit_20260616/metadata.json new file mode 100644 index 00000000..e3b8b1ba --- /dev/null +++ b/conductor/tracks/exception_handling_audit_20260616/metadata.json @@ -0,0 +1,194 @@ +{ + "track_id": "exception_handling_audit_20260616", + "name": "Exception Handling Audit (Convention Compliance + Doc Clarification)", + "initialized": "2026-06-16", + "completed_at": "2026-06-16", + "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": { + "phase_1": "30 min - spec + plan + metadata + tracks.md", + "phase_2": "1-2 hours - audit script + verifications (script already drafted in spec phase)", + "phase_3": "1-2 hours - 5 doc/codestyle updates (small additions)", + "phase_4": "30 min - final report + metadata update", + "phase_5": "5 min - user manual verification (the user reviews the report)", + "total": "0.5 day Tier 2 work (2-4 hours)" + }, + + "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." + } +}