ed
aba35f9f4a
Per user feedback (2026-06-06): instead of a follow-up 'TypedDict Migration' track, add a NEW deliverable: an auto-generated type registry in docs/type_registry/ that captures the field information in docs form. New files: - scripts/generate_type_registry.py (NEW): AST-based tool that reads src/ and writes per-source-file .md files with the fields of every @dataclass, NamedTuple, TypeAlias, TypedDict. Has --check (CI mode, exits 1 if registry would change) and --diff (dry run) modes. - docs/type_registry/ (NEW, generated): index.md + per-source-file references (type_aliases.md, ai_client.md, models.md, etc.). - tests/test_generate_type_registry.py (NEW): verify the generator. Architecture updates: - Section 3.6 (NEW): Type Registry architecture with example output. - Section 3.7 (NEW): Why per-source-file docs (locality of reference). - Section 1.1 (NEW): 'Why docs over TypedDict' analysis (3 reasons: lower upfront cost, better fit for AI workflow, auto-maintained). - Goals table: registry added as a C (innovation) goal. - Module layout: docs/type_registry/ and scripts/generate_type_registry.py added to the new files list. - Migration: Phase 2 now includes the registry generator + initial docs. - Out of scope: TypedDict migration REMOVED; 'auto-typing the field shape' added with the docs as the chosen approach. - See Also: TypedDict follow-up REPLACED with 'Registry Maintenance & CI Integration' (smaller scope, just wires the generator into CI). The 'cost we eat' is the LLM reading 200-500 lines of markdown per query. This is bounded and proportional to actual information need. The upfront cost of designing TypedDict schemas for every type is unbounded. Tradeoffs favor the docs approach for v1; TypedDict can come later as a future track if desired.
96 lines
7.2 KiB
TOML
96 lines
7.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 + 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."
|