From 134ed4fb1b713f6b6d9d703a3189f8fac9dd0a03 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Wed, 17 Jun 2026 21:51:25 -0400 Subject: [PATCH] docs(track): update result_migration_20260616 umbrella with sub-track 2 shipped status --- .../tracks/result_migration_20260616/spec.md | 72 ++++++++++++++++--- 1 file changed, 61 insertions(+), 11 deletions(-) diff --git a/conductor/tracks/result_migration_20260616/spec.md b/conductor/tracks/result_migration_20260616/spec.md index d0dde7c9..accb543c 100644 --- a/conductor/tracks/result_migration_20260616/spec.md +++ b/conductor/tracks/result_migration_20260616/spec.md @@ -37,7 +37,7 @@ sites** across the codebase. **5 sub-tracks with consistent `result_migration_*` prefix:** 1. `result_migration_review_pass` (T-shirt: S) — 57 sites (32 UNCLEAR + 25 INTERNAL_RETHROW); updates the audit's heuristics -2. `result_migration_small_files` (T-shirt: L) — 37 files (35 SMALL + 2 MEDIUM; 72 V+S sites) +2. `result_migration_small_files` (T-shirt: L) — 37 files (35 SMALL + 2 MEDIUM); **shipped 2026-06-17** with documented G4 deviation: 76 sites (62V + 10S + 4 UNCLEAR) → 49 migrated (6 full `Result[T]` + 43 exception narrowing) + 13 already compliant + 27 silent-swallow sites remain (follow-up sub-track planned) 3. `result_migration_app_controller` (T-shirt: XL) — 56 sites (35 V + 3 S + 2 ? + 16 C; 13 FastAPI boundary stay as-is) 4. `result_migration_gui_2` (T-shirt: XL) — **55 sites** (37 V + 2 S + **14 ?** + 2 C; the 14 ? includes the +1 site from the review pass: `src/gui_2.py:1349`) 5. `result_migration_baseline_cleanup` (T-shirt: L) — 112 sites (77 V + 10 S + 6 ? + 19 C in the 3 refactored files) @@ -52,6 +52,17 @@ sites** across the codebase. > - **19 INTERNAL_RETHROW sites** are all compliant: 7 PATTERN_1 (Result→Exception bridge in baseline files) + 2 PATTERN_2 (catch+log+re-raise) + 9 compliant (standard `__getattr__`, abstract method, validation raise) + 1 audit-script bug (missed find) > - Net migration scope change: **sub-track 4 (gui_2) gains 1 site** (L1349). All other sub-tracks are unchanged. +> **Post-Sub-Track-2 Update (2026-06-17, sub-track 2 shipped):** +> After the small-files migration (`result_migration_small_files_20260617`), +> the audit script is now correct (3 bugs fixed in Phase 1 of that sub-track), +> and the 37 SMALL+MEDIUM files have been processed: +> - **49/76 sites migrated** (6 full `Result[T]` + 43 exception narrowing) + 13 already compliant +> - **27 sites remain `INTERNAL_SILENT_SWALLOW`** (narrow-catch + pass); follow-up sub-track planned +> - **Audit's UNCLEAR count: 7 → 21** (+14 sites) — the narrowing created patterns the audit's heuristics don't recognize; follow-up sub-track will add 2-3 new heuristics +> - **Bonus defensive fix:** `try/except (OSError, tomllib.TOMLDecodeError)` in `load_track_state` unblocked 7+ tests +> - **Test result:** all 11 test tiers PASS (tier-1-unit-comms, tier-1-unit-core, tier-1-unit-gui, tier-1-unit-headless, tier-1-unit-mma, tier-2-mock_app-comms, tier-2-mock_app-core, tier-2-mock_app-gui, tier-2-mock_app-headless, tier-2-mock_app-mma, tier-3-live_gui) +> - **Documented G4 deviation:** 27 silent-swallow sites remain. A follow-up sub-track `result_migration_silent_swallow_followup_` is planned (TBD; see "Recommended Sequence" below for the new ordering) + --- ## 1. Overview @@ -114,22 +125,61 @@ applied. Both feed into all later sub-tracks. #### Sub-track 2: `result_migration_small_files_` **Scope:** 37 files (the 35 SMALL + 2 MEDIUM from the `--by-size` bucket); -72 V+S sites. -**T-shirt size:** L (batched; ~700 lines changed across 37 files; mechanical). +**76 sites (62V + 10S + 4 UNCLEAR) → 49 migrated + 13 already compliant + 27 silent-swallow remain.** +**T-shirt size:** L (batched; ~750 lines changed across 37 files + 1 audit script + 1 new test file). +**Status:** **shipped 2026-06-17** with documented G4 deviation (27 sites remain `INTERNAL_SILENT_SWALLOW`; follow-up sub-track planned). **Why second:** the small files are quick wins; they don't depend on the orchestrator (app_controller) or the GUI. Some of them DO depend on sub-track 1's review pass (so the UNCLEAR sites are classified first). +Phase 1 of this sub-track (audit-script bug fixes) unblocks sub-tracks +3 and 4 by giving them an audit that classifies correctly. -**What it does:** -- Migrates each of the 37 files to the convention. -- Each file's migration is a small `Result[T]` introduction + an - `except as e: return Result(data=NIL_T, errors=[ErrorInfo(...)])` - replacement. -- The 2 MEDIUM files (session_logger, warmup) get dedicated commits; the - 35 SMALL files get batched commits (5-7 files per commit). +**What it did:** +- **Phase 1: 3 audit-script bug fixes** (TDD) — fixed the 3 bugs documented + in the review-pass report §4.4: + - `visit_Try` walker now visits ALL except handlers (was only walking the last) + - `render_json` per-file list now includes all findings (was filtering compliant) + - `render_json` no longer truncates per-file list to top 15 (default now 200) +- **Phase 2: 4 UNCLEAR classifications** (2 migration-target + 2 compliant; decisions in + `docs/reports/RESULT_MIGRATION_SMALL_FILES_20260617.md`) +- **Phases 3-8: 49/76 sites migrated** using two strategies: + - **Strategy A: Full `Result[T]` migration** (2 files, 6 sites): `summary_cache.py`, `log_registry.py`. + Backwards-compatible (callers ignore the Result return). + - **Strategy B: Exception narrowing** (24 files, 43 sites): changed `except Exception` + to specific stdlib/domain exceptions. Public API unchanged; behavior unchanged; no + caller updates needed. This is a **partial migration** — the convention's FR4 + says "convert to Result[T]", but the spec also acknowledged (R5) that cascading + public API changes may be acceptable. Tier 2 chose narrowing for 43 sites to + avoid ~100+ caller updates. **Caveat:** narrowing without `logging.warning(...)` + is **silent recovery** (no trace). The 27 sites that remain `INTERNAL_SILENT_SWALLOW` + are documented in the track completion report; a follow-up sub-track is + planned to add logging or full Result migration to them. +- **Phase 9: Verification** — all 11 test tiers PASS; per-site report + track + completion report written; state.toml + metadata.json marked completed. +- **Bonus defensive fix:** `try/except (OSError, tomllib.TOMLDecodeError)` in + `load_track_state` (in `src/project_manager.py`) for a pre-existing malformed + state.toml crash. Unblocked 7+ tests. -**Dependency:** sub-track 1 (for the UNCLEAR classification). +**Documented G4 deviation:** 27 sites remain `INTERNAL_SILENT_SWALLOW` (narrow-catch + +pass or narrow-catch + return None). These are categorized as: +- **Category A (intentional silent recovery, 17 sites):** Known failure modes where the + caller has no use for the error info (e.g., `file_cache.py:98` mtime cache fallback, + `outline_tool.py:90` ast.unparse fallback, `startup_profiler.py:40` profile output + with `stderr.write` as a log). Should add `logging.debug(...)` per the audit's + heuristic #19 to confirm intent. +- **Category B (user-input-driven, 10 sites):** Callbacks and reload paths where any + exception is possible (e.g., `warmup.py:139/215/249` user callbacks, `hot_reloader.py:58` + module reload). Should add `logging.warning(...)` to surface user errors. + +**Migration-target sites introduced by the narrowing:** the audit's UNCLEAR count +went **7 → 21** (+14 sites) because the narrowing created patterns the audit's +heuristics don't recognize. A follow-up sub-track is planned to add 2-3 new heuristics +(heavily-narrowed `except` without logging; `except` returning Result in non-`*_result` +function) that reclassify these. + +**Dependency:** sub-track 1 (for the UNCLEAR classification). Unblocks sub-tracks 3 and 4 +by fixing the audit script. #### Sub-track 3: `result_migration_app_controller_`