196 lines
11 KiB
JSON
196 lines
11 KiB
JSON
{
|
|
"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."
|
|
}
|
|
}
|