# 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 + type registry generator + initial 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 + type registry generator + initial 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 = "Red: tests/test_generate_type_registry.py (verify AST extraction of @dataclass, NamedTuple, TypeAlias; verify output markdown structure)" }
t2_4 = { status = "pending", commit_sha = "", description = "Green: implement scripts/generate_type_registry.py (3 modes: default, --check, --diff)" }
t2_5 = { status = "pending", commit_sha = "", description = "Run the generator; commit the initial docs/type_registry/ (index.md + per-source-file .md files)" }
t2_6 = { status = "pending", commit_sha = "", description = "Verify --check mode: introduce a fake change in src/type_aliases.py, run --check, confirm exit 1" }
t2_7 = { status = "pending", commit_sha = "", description = "Create conductor/code_styleguides/type_aliases.md (canonical reference for the alias convention; 5 patterns + decision tree + examples)" }
t2_8 = { status = "pending", commit_sha = "", description = "Add 'Data Structure Conventions' section to conductor/product-guidelines.md (referencing the new styleguide)" }
t2_9 = { status = "pending", commit_sha = "", description = "Manual smoke test: launch GUI; verify type aliases don't break anything; verify audit --strict mode; verify generator --check mode" }
t2_10 = { status = "pending", commit_sha = "", description = "Phase 2 checkpoint commit + git note (TRACK COMPLETE)" }
t2_11 = { status = "pending", commit_sha = "", description = "git mv conductor/tracks/data_structure_strengthening_20260606 to conductor/tracks/archive/" }
t2_12 = { status = "pending", commit_sha = "", description = "Update conductor/tracks.md: move entry to Recently Completed" }
t2_13 = { status = "pending", commit_sha = "", description = "Final state.toml update: mark all phases completed; add follow-up track type_registry_ci_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 = "type_registry_ci_20260606"
status = "planned_in_data_structure_strengthening_20260606"
goal = "Promote the type-registry generator from a manual track-completion step to a CI gate. Add --check to CI; wire pre-commit hook; document the per-track commit workflow."
note = "This follow-up REPLACES the earlier 'typed_dict_migration' follow-up. Per user feedback (2026-06-06), the registry approach (docs) is preferred over TypedDict migration (code) for the foreseeable future."

[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."