TIER-1 READ AGENTS.md + conductor/workflow.md + conductor/edit_workflow.md
+ conductor/code_styleguides/data_oriented_design.md + conductor/code_styleguides/error_handling.md
+ conductor/code_styleguides/type_aliases.md + conductor/code_styleguides/code_path_audit.md
+ conductor/tracks/module_taxonomy_refactor_20260627/spec.md + conductor/tracks/module_taxonomy_refactor_20260627/plan.md
+ docs/reports/FOLLOWUP_module_taxonomy_refactor_20260627_recoverable.md before this commit.
v2 fixes v1 gaps that gave Tier 2 discretion:
1. THE 4-CRITERIA DECISION RULE (the taxonomy law):
- C1: Cross-system usage (consumed by >= 3 unrelated systems)
- C2: State machine / lifecycle
- C3: Test file already exists
- C4: Substantial size (> 30 lines OR > 5 fields)
- Rule: C1 OR C2 OR C3 -> DEDICATED FILE; ONLY C4 -> MERGE INTO DESTINATION; NONE -> KEEP
2. THE DATA/VIEW/OPS SPLIT (the GUI boundary):
- Data classes go in data files (src/<system>.py)
- View code (ImGui rendering) goes in src/gui_2.py
- Ops (operations on data) go with the data
- Exception: imgui_scopes.py is the EXCEPTION (Python with context managers)
3. ZERO TIER 2 DISCRETION:
- Every move is pre-decided in the spec
- Tier 2 executes, doesn't decide
- v1 had 22 commits because of exploration; v2 has 16 because the work is prescriptive
4. PRESERVED Pydantic PROXIES:
- _create_generate_request, _create_confirm_request, __getattr__ stay in models.py
- They're API-specific; moving them is out of scope for v2
Applied to all 11 classes in models.py:
- DEDICATED: Ticket, Track, WorkerContext, TrackState, TrackMetadata, ThinkingSegment -> src/mma.py (6 classes; C1+C2+C3+C4)
- DEDICATED: FileItem, Preset, ContextPreset, ContextFileEntry, NamedViewPreset -> src/project_files.py (5 classes; C1+C3+C4)
- DEDICATED: ProjectContext + 5 sub + config IO -> src/project.py (1+5+functions; C1+C3+C4)
- MERGE: Tool, ToolPreset -> src/tool_presets.py (C1 NO)
- MERGE: BiasProfile -> src/tool_bias.py (C1 NO)
- MERGE: TextEditorConfig, ExternalEditorConfig -> src/external_editor.py (C1 NO)
- MERGE: Persona -> src/personas.py (C1 NO)
- MERGE: WorkspaceProfile -> src/workspace_manager.py (C1 NO)
- MERGE: MCPServerConfig, MCPConfiguration, VectorStoreConfig, RAGConfig, load_mcp_config -> src/mcp_client.py (C1 YES, coupled to MCP)
- DELETE: AGENT_TOOL_NAMES (redundant with mcp_tool_specs.tool_names())
Net: 65 -> 61 files (possibly 60 if models.py eliminated)
16 atomic commits (down from v1's 22)
14 VCs (added VC13 + VC14: verify the 4-criteria rule and data/view/ops split are documented)
The git stash ban is in place at 3 layers (commit 6240b07b). The timeline-
is-immutable principle is explicit in the agent prompt. The next Tier 2
should not be able to corrupt files the same way.
Tier 2 marked Phase 2 (VC8) as 'spec mismatch' because the spec says
'add ProjectContext with all fields observed in flat_config' but
doesn't enumerate which fields. Tier 2 needs the spec to be specific
before it can resume.
This correction specifies the exact schema based on the actual code:
flat_config returns a NESTED dict with 6 top-level fields:
- project (Meta: name, summary_only, execution_mode)
- output (Output: namespace, output_dir)
- files (Files: base_dir, paths)
- screenshots (Screenshots: base_dir, paths)
- context_presets (opaque dict pass-through)
- discussion (Discussion: roles, history)
The 11 sub-fields are derived from aggregate.run's access patterns
(src/aggregate.py:484-525). output_dir and files.base_dir are REQUIRED
(direct subscript); all others use .get() with defaults.
Recommended design: 6 sub-dataclasses (ProjectMeta, ProjectOutput,
ProjectFiles, ProjectScreenshots, ProjectDiscussion, ProjectContext),
each matching the nested dict shape. ProjectContext has dict-compat
methods (__getitem__ + get) so consumers don't need migration.
Two migration options:
- Option A (incremental): ProjectContext has dict-compat; consumers
unchanged. Flat fix.
- Option B (full): Migrate all 8 consumer sites + 2 test mocks to
use sub-dataclass access. ~40 lines across 10 files.
Acceptance: 5 corrected VC8 criteria. Tier 2 can resume Phase 2 directly.
TIER-1 READ conductor/tracks/cruft_elimination_20260627/spec.md + src/project_manager.py:268 + src/aggregate.py:484-525 + src/type_aliases.py + src/models.py before this commit.
The previous state.toml marked status = 'completed' despite the
track FAILING 4 of 10 acceptance criteria:
- VC1: .get() sites 26 (target < 15)
- VC2: subscript sites 79 (target < 20)
- VC4: effective codepaths not measured
- VC6: 7/11 batched tiers pass (target 10/11)
This commit:
1. Sets state.toml status to 'active' (track is NOT complete)
2. Marks Phase 11 as 'failed' (verification did not pass)
3. Rewrites the completion report to lead with the FAILED status
The 50% reduction in .get() sites (52 -> 26) is meaningful progress
but the spec's quantitative gates were not met. Do not merge this
branch as complete.
src/type_aliases.py had two exact anti-patterns the user flagged:
1. Line 91: 'ToolCall: TypeAlias = Metadata' -- the dict alias the user
called out as 'the exact bad pattern'. Now points to the canonical
@dataclass(frozen=True, slots=True) class ToolCall in openai_schemas.py.
2. Lines 53-69: duplicate FileItem dataclass with 8 fields (path, content,
view_mode, summary, skeleton, annotations, tags) that conflicted with
the canonical models.FileItem (10 fields: path, auto_aggregate,
force_full, view_mode, selected, ast_signatures, ast_definitions,
ast_mask, custom_slices, injected_at). Two FileItem types was the
'FileItem is duplicated in TWO places' blocker. Duplicate removed;
FileItem now aliases models.FileItem.
state.toml updated to honest state: status='active', current_phase=0,
phases 2-10 marked 'not_done', 3 of 5 blockers fixed in this commit,
2 blockers (RAG return type, tool builders dicts) remain open with
followup tracks planned.
The 5 files that import ToolCall from src.type_aliases
(aggregate/ai_client/api_hook_client/app_controller/models) only use it
as a type annotation -- no constructor calls, no .from_dict() calls.
Safe to fix the alias.
The previous Tier 2 run marked the track SHIPPED with all 12 phases
'completed' but did not do the actual Phase 1 (Ticket consumer migration)
work. This run did Phase 1 honestly in commit 0506c5da.
This commit:
- Updates state.toml to reflect actual Phase 1 work (with checkpoint
0506c5da) and re-classifies Phases 2-10 as no-op per FR2 audit
- Replaces the misleading TRACK_COMPLETION report with an honest
re-assessment: Phase 1 done, Phases 2-10 no-op per audit (planned
sites operate on collapsed-codepath dicts), VC7 metric unchanged
(expected per Tier 1 followup analysis: per-aggregate migration alone
doesn't reduce dispatcher branch count)
Verification criteria status:
- VC1-VC3, VC6, VC8, VC10: PASS
- VC4, VC5, VC9: PARTIAL
- VC7: NO DROP (4.014e+22 unchanged; requires typed parameters at
function boundaries, which is out of scope)
Phases 3-10 audit found that all anticipated migration sites operate on
dicts at the I/O boundary (session log entries from JSONL, multimodal
content with arbitrary keys, MCP wire protocol, project config from
manual_slop.toml). Per spec FR2 (collapsed-codepath classification),
these dict-style access patterns are correctly preserved as Metadata.
Real work was done in Phase 0 (12 NEW per-aggregate dataclasses added)
and the test suite (70+ tests). The NEW dataclasses are AVAILABLE for
future code that wants typed access; existing code is correct in its
dict usage at the I/O boundaries.
Effective codepaths metric UNCHANGED at 4.014e+22 (the metric is
dominated by type-dispatch branches in app_controller.py and gui_2.py,
not by the .get() access sites themselves).
Phase 2 audit confirmed no FileItem dataclass access sites need migration:
- All file_items: list[Metadata] sites are multimodal content dicts (not FileItem dataclass)
- FileItem dataclass consumers (app_controller.py:3231-3237, 3401-3408, gui_2.py:369-378, 977-984) already use direct field access
- The .get() sites are correctly classified as Metadata collapsed-codepath per FR2
8/8 tests pass + 1 env-var skipped. No code changes needed.
Phase 1 audit confirmed no Ticket dataclass access sites need migration:
- Ticket dataclass consumers in _spawn_worker, mutate_dag, and
multi_agent_conductor.run already use direct field access
- The t.get('id', '') style sites operate on dicts
(self.active_tickets: list[Metadata], topological_sort returns list[dict])
- These dict sites are correctly classified as Metadata collapsed-codepath
per spec FR2
35/35 tests pass. No code changes needed.
The actual fix for the 4.01e22 combinatoric explosion. Promotes
Metadata: TypeAlias = dict[str, Any] to @dataclass(frozen=True, slots=True)
and migrates all 695 consumer functions + 213 access sites (107 .get +
106 subscript) to direct field access.
TIER-1 READ AGENTS.md + conductor/workflow.md + conductor/edit_workflow.md
+ conductor/code_styleguides/data_oriented_design.md + conductor/code_styleguides/error_handling.md + conductor/code_styleguides/type_aliases.md + docs/reports/SSDL_CAMPAIGN_ABORTED_20260624.md + src/type_aliases.py + scripts/code_path_audit/code_path_audit.py + scripts/code_path_audit/code_path_audit_ssdl.py before this commit.
Why this fixes 4.01e22:
- The combinatoric explosion is from dict[str, Any] type-dispatch at every
entry.get('key', default) site (per SSDL post-mortem)
- Each access has 3 branches: is None, getattr, default
- 695 consumers * ~2 branches each = 1390 branches in the sum
- 2^1390 ≈ 4.01e22 (the measured baseline)
- Promotion to @dataclass with direct field access = 0 branches per access
- Expected drop: 4.014e+22 -> < 1e+20 (>= 2 orders of magnitude)
10 VCs:
- VC1: Metadata is @dataclass(frozen=True, slots=True), not dict[str, Any]
- VC2: 107 .get sites replaced
- VC3: 106 subscript sites replaced
- VC4: 12+ tests pass in tests/test_metadata_dataclass.py
- VC5: 5 sub-aggregate TypeAliases (CommsLogEntry, HistoryMessage, FileItem,
ToolDefinition, ToolCall) all point to the new Metadata
- VC6: Effective codepaths < 1e+20
- VC7: All 7 audit gates pass --strict
- VC8: 10/11 batched test tiers PASS
- VC9: End-of-track report written
- VC10: New regression-guard test file exists
5-phase phased migration (smallest sub-aggregate first):
- Phase 1: CommsLogEntry (~150 sites in session_logger, multi_agent_conductor, app_controller)
- Phase 2: HistoryMessage (~80 sites in ai_client)
- Phase 3: FileItem (~200 sites in aggregate, app_controller, gui_2)
- Phase 4: ToolDefinition+ToolCall (~150 sites in mcp_client, ai_client tool loop)
- Phase 5: Metadata direct usage (~115 sites catch-all)
6 phases total (0 + 5 + verification). 18-21 atomic commits.
blocked_by: code_path_audit_phase_3_provider_state_20260624 (recommended prerequisite;
the two tracks are orthogonal so they can run in parallel; listed as blocked_by
for sequencing preference not strict blocking)
The 7 code_path_audit*.py files (2604 lines total) are pure static
analysis tools. They do AST traversal of src/, no intrusive profiling,
no runtime markers. They were inlaid with src/ but only import:
- src.result_types (the Result[T] convention type)
- each other (the 6 siblings)
After the move:
- src/ is now pure application code; line-count audit metrics are clean
- scripts/code_path_audit/ is a new namespace-isolated subdir per
AGENTS.md 'scripts are namespace-isolated by directory' rule
TIER-3 READ AGENTS.md + conductor/workflow.md + conductor/edit_workflow.md
+ conductor/code_styleguides/code_path_audit.md + the 7 files before
this commit.
Changes:
- 7 files moved: src/code_path_audit*.py -> scripts/code_path_audit/
- 7 files updated: internal imports rom src.code_path_audit_X ->
rom code_path_audit_X (siblings in same subdir)
- 7 files updated: add sys.path.insert(0, str(Path(__file__).resolve().parents[2] / 'src'))
to find src.result_types when run standalone
- 5 test files updated: rom src.code_path_audit -> rom code_path_audit
+ sys.path setup to find the new subdir
- 6 throwaway scripts in scripts/tier2/artifacts/ updated: import path
+ sys.path setup (parents[3] / 'src' + parents[3] / 'scripts' / 'code_path_audit')
- 2 styleguide/spec references updated: conductor/code_styleguides/code_path_audit.md
+ conductor/tracks/code_path_audit_20260607/spec_v2.md
- 1 meta-audit docstring updated: scripts/audit_code_path_audit_coverage.py
- 1 type registry entry deleted: docs/type_registry/src_code_path_audit.md
(the type is no longer in src/)
- 1 type registry index updated: docs/type_registry/index.md (22 files, was 23)
Verification:
- 7/7 audit gates pass --strict (weak_types 102<=112, type_registry 22 files,
main_thread_imports OK, no_models_config_io OK, code_path_audit_coverage 0
violations, exception_handling 0 violations, optional_in_3_files 0 violations)
- 6/6 test files pass: test_code_path_audit, test_code_path_audit_integration,
test_code_path_audit_phase78, test_code_path_audit_phase89,
test_code_path_audit_ssdl_behavioral, test_metadata_nil_sentinel
- src/ line count: 29997 lines (down from 32621 = -2624 lines)
- scripts/code_path_audit/ line count: 2620 lines
ed