ed
ed42a97a9b
Track + metadata + state + tracks.md registration for the type-aliases refactor that follows the audit_weak_types.py findings (430 weak sites across 29 of 61 files; 86% concentrated in 6 high-traffic files). Key design decisions (per user approval): - 10 TypeAlias definitions in src/type_aliases.py (Metadata, CommsLogEntry, CommsLog, HistoryMessage, History, FileItem, FileItems, ToolDefinition, ToolCall, CommsLogCallback). - 1 NamedTuple (FileItemsDiff) for the _reread_file_items return. - Mechanical replacement of 345 weak sites across 6 files (NOT 430; the remaining 85 are in 23 lower-impact files deferred to future tracks). - scripts/audit_weak_types.py gains a --strict mode and a baseline file (scripts/audit_weak_types.baseline.json) so the count is enforced. - 2 phases: aliases + 6-file replacement + audit baseline; NamedTuples + docs + archive. - Honest about what's missing: TypedDict / @dataclass migration is a follow-up track (typed_dict_migration_20260606), not this one. - Coexistence with the data_oriented_error_handling_20260606 track's Result[T] / ErrorInfo: the aliases are value-level (data types), Result is control-level (wrapper). They compose (Result[FileItems] is valid). No conflict. Audit baseline: - Pre-track: 430 weak sites, 0 strong patterns - Target after Phase 1: ~60 weak sites (only the 23 lower-impact files) - Top 4 unique type strings account for 86% of findings (4-6 aliases eliminate the bulk of the noise). Not blocked by anything; can be executed independently of the other pending tracks. Blocks typed_dict_migration_20260606 (the future Phase 2).
92 lines
6.2 KiB
TOML
92 lines
6.2 KiB
TOML
# Track state for data_structure_strengthening_20260606
|
|
# Updated by Tier 2 Tech Lead as tasks complete
|
|
|
|
[meta]
|
|
track_id = "data_structure_strengthening_20260606"
|
|
name = "Data Structure Strengthening (Type Aliases + NamedTuples)"
|
|
status = "active"
|
|
current_phase = 0
|
|
last_updated = "2026-06-06"
|
|
|
|
[phases]
|
|
phase_1 = { status = "pending", checkpointsha = "", name = "Aliases + 6-file replacement + audit baseline" }
|
|
phase_2 = { status = "pending", checkpointsha = "", name = "NamedTuples + docs + archive" }
|
|
|
|
[tasks]
|
|
# Phase 1: Aliases + 6-file replacement
|
|
t1_1 = { status = "pending", commit_sha = "", description = "Red: tests/test_type_aliases.py (verify 10 TypeAliases + 1 NamedTuple import and resolve to expected types; verify Result[FileItems] composes)" }
|
|
t1_2 = { status = "pending", commit_sha = "", description = "Green: create src/type_aliases.py with 10 TypeAliases (Metadata, CommsLogEntry, CommsLog, HistoryMessage, History, FileItem, FileItems, ToolDefinition, ToolCall, CommsLogCallback) and 1 NamedTuple (FileItemsDiff)" }
|
|
t1_3 = { status = "pending", commit_sha = "", description = "Replace 139 weak sites in src/ai_client.py with the new aliases (79 dict_str_any + 56 list_of_dict + 2 Optional[List[Dict]] + 2 assign_tuple_literal)" }
|
|
t1_4 = { status = "pending", commit_sha = "", description = "Replace 86 weak sites in src/app_controller.py (62 dict_str_any + 20 list_of_dict + 4 optional_dict)" }
|
|
t1_5 = { status = "pending", commit_sha = "", description = "Replace 51 weak sites in src/models.py (48 dict_str_any + 3 list_of_dict)" }
|
|
t1_6 = { status = "pending", commit_sha = "", description = "Replace 32 weak sites in src/api_hook_client.py (30 dict_str_any + 2 list_of_dict)" }
|
|
t1_7 = { status = "pending", commit_sha = "", description = "Replace 20 weak sites in src/project_manager.py (16 dict_str_any + 3 list_of_dict + 1 optional_dict)" }
|
|
t1_8 = { status = "pending", commit_sha = "", description = "Replace 17 weak sites in src/aggregate.py (10 dict_str_any + 7 list_of_dict)" }
|
|
t1_9 = { status = "pending", commit_sha = "", description = "Add --strict mode to scripts/audit_weak_types.py (compares current count to baseline file; exits 1 if increased)" }
|
|
t1_10 = { status = "pending", commit_sha = "", description = "Generate scripts/audit_weak_types.baseline.json with the post-Phase-1 count" }
|
|
t1_11 = { status = "pending", commit_sha = "", description = "Red: tests/test_audit_weak_types.py (verify regex patterns, Finding dataclass, report format)" }
|
|
t1_12 = { status = "pending", commit_sha = "", description = "Run full test suite; confirm no regressions in 6 refactored files" }
|
|
t1_13 = { status = "pending", commit_sha = "", description = "Run audit; confirm count dropped from 430 to ~60; commit the new baseline" }
|
|
t1_14 = { status = "pending", commit_sha = "", description = "Phase 1 checkpoint commit + git note" }
|
|
# Phase 2: NamedTuples + docs + archive
|
|
t2_1 = { status = "pending", commit_sha = "", description = "Convert src/ai_client.py:_reread_file_items to return FileItemsDiff NamedTuple (replaces Tuple[List[FileItem], List[FileItem]]); update ~3-4 call sites" }
|
|
t2_2 = { status = "pending", commit_sha = "", description = "Opportunistic NamedTuple conversions for 1-2 more tuple returns (screen coords, etc.)" }
|
|
t2_3 = { status = "pending", commit_sha = "", description = "Create conductor/code_styleguides/type_aliases.md (canonical reference for the alias convention; 5 patterns + decision tree + examples)" }
|
|
t2_4 = { status = "pending", commit_sha = "", description = "Add 'Data Structure Conventions' section to conductor/product-guidelines.md (referencing the new styleguide)" }
|
|
t2_5 = { status = "pending", commit_sha = "", description = "Manual smoke test: launch GUI; verify type aliases don't break anything; verify audit --strict mode" }
|
|
t2_6 = { status = "pending", commit_sha = "", description = "Phase 2 checkpoint commit + git note (TRACK COMPLETE)" }
|
|
t2_7 = { status = "pending", commit_sha = "", description = "git mv conductor/tracks/data_structure_strengthening_20260606 to conductor/tracks/archive/" }
|
|
t2_8 = { status = "pending", commit_sha = "", description = "Update conductor/tracks.md: move entry to Recently Completed" }
|
|
t2_9 = { status = "pending", commit_sha = "", description = "Final state.toml update: mark all phases completed; add follow-up track typed_dict_migration_20260606 placeholder" }
|
|
|
|
[verification]
|
|
# Filled as phases complete
|
|
phase_1_aliases_module_complete = false
|
|
phase_1_ai_client_refactored = false
|
|
phase_1_app_controller_refactored = false
|
|
phase_1_models_refactored = false
|
|
phase_1_api_hook_client_refactored = false
|
|
phase_1_project_manager_refactored = false
|
|
phase_1_aggregate_refactored = false
|
|
phase_1_audit_strict_mode_added = false
|
|
phase_1_baseline_committed = false
|
|
phase_2_file_items_diff_named_tuple = false
|
|
phase_2_opportunistic_named_tuples = false
|
|
phase_2_styleguide_written = false
|
|
phase_2_product_guidelines_updated = false
|
|
phase_2_smoke_test_passed = false
|
|
phase_2_track_archived = false
|
|
full_test_suite_passes = false
|
|
no_new_optional_introduced = false
|
|
audit_count_dropped_to_60 = false
|
|
|
|
[audit_count_progression]
|
|
# Filled as tasks complete
|
|
baseline = 430
|
|
after_ai_client = 291
|
|
after_app_controller = 205
|
|
after_models = 154
|
|
after_api_hook_client = 122
|
|
after_project_manager = 102
|
|
after_aggregate = 85
|
|
phase_1_checkpoint_committed = 0 # TBD
|
|
phase_2_checkpoint_committed = 0 # TBD
|
|
|
|
[files_refactored]
|
|
ai_client = { weak_sites_before = 139, weak_sites_after = 0, status = "pending" }
|
|
app_controller = { weak_sites_before = 86, weak_sites_after = 0, status = "pending" }
|
|
models = { weak_sites_before = 51, weak_sites_after = 0, status = "pending" }
|
|
api_hook_client = { weak_sites_before = 32, weak_sites_after = 0, status = "pending" }
|
|
project_manager = { weak_sites_before = 20, weak_sites_after = 0, status = "pending" }
|
|
aggregate = { weak_sites_before = 17, weak_sites_after = 0, status = "pending" }
|
|
|
|
[typed_dict_migration_followup]
|
|
track_id = "typed_dict_migration_20260606"
|
|
status = "planned_in_data_structure_strengthening_20260606"
|
|
converts = ["CommsLogEntry", "FileItem", "ToolDefinition", "HistoryMessage"]
|
|
to = "TypedDict or @dataclass(frozen=True)"
|
|
|
|
[public_api_migration_followup]
|
|
# From the data_oriented_error_handling track
|
|
note = "This track does not depend on or block the public_api_migration_20260606 track. They are independent."
|