{
  "track_id": "metadata_promotion_20260624",
  "name": "Metadata Promotion: dict[str, Any] -> @dataclass(frozen=True, slots=True)",
  "status": "active",
  "type": "fix",
  "parent": "any_type_componentization_20260621",
  "grandparent": "code_path_audit_20260607",
  "date_created": "2026-06-25",
  "created_by": "tier1-orchestrator",
  "blocks": [],
  "blocked_by": {
    "code_path_audit_phase_3_provider_state_20260624": "pending (not started yet; recommended prerequisite to run in parallel)"
  },
  "scope": {
    "new_files": [
      "tests/test_metadata_dataclass.py",
      "docs/reports/metadata_promotion_progress.md"
    ],
    "modified_files": [
      "src/type_aliases.py"
    ],
    "consumer_files": [
      "src/session_logger.py",
      "src/multi_agent_conductor.py",
      "src/app_controller.py",
      "src/ai_client.py",
      "src/aggregate.py",
      "src/gui_2.py",
      "src/mcp_client.py",
      "src/models.py",
      "src/paths.py",
      "src/synthesis_formatter.py"
    ]
  },
  "verification_criteria": [
    "Metadata is @dataclass(frozen=True, slots=True), not dict[str, Any]",
    "All 107 .get('key', ...) access sites on Metadata consumers replaced",
    "All 106 ['key'] subscript access sites on Metadata consumers replaced",
    "tests/test_metadata_dataclass.py: 12+ tests pass",
    "All 5 sub-aggregate TypeAliases (CommsLogEntry, HistoryMessage, FileItem, ToolDefinition, ToolCall) point to the new Metadata",
    "Effective codepaths drops by >= 2 orders of magnitude (< 1e+20; was 4.014e+22)",
    "All 7 audit gates pass --strict (no regression)",
    "10/11 batched test tiers PASS (RAG flake acceptable)",
    "End-of-track report written (docs/reports/TRACK_COMPLETION_metadata_promotion_20260624.md)",
    "New regression-guard test file (tests/test_metadata_dataclass.py)"
  ],
  "estimated_effort": {
    "method": "scope (per workflow.md \u00a7Tier 1 Track Initialization Rules). NO day estimates.",
    "scope": "1 source file replaced (src/type_aliases.py: 30 lines -> ~200 lines for the dataclass) + 1 new test file (12+ tests) + 10 consumer files modified (~213 access sites total) + 6 phase checkpoint commits; estimated 18-21 atomic commits total"
  },
  "risk_register": [
    "R1 (medium): 213 access sites have polymorphic keys that don't fit cleanly into a single dataclass - mitigated by Optional[T] for all fields + from_dict() classmethod + to_dict() for serialization",
    "R2 (low): Some sites do entry['key'] with dynamic keys - mitigated by keeping dict-style access for dynamic keys via entry.to_dict()[var_name]",
    "R3 (low): to_dict() round-trip loses information for nested dicts - mitigated by careful implementation; nested dicts pass through as dict[str, Any]",
    "R4 (medium): Some sites mutate entry (e.g., entry['key'] = value); dataclass is frozen - mitigated by audit + replacement with dataclasses.replace()",
    "R5 (low): Migration breaks regression-guard tests - mitigated by per-phase regression-guard test runs",
    "R6 (high): 695 consumer functions are too many for one track - mitigated by 5-phase sub-aggregate migration; each phase independent",
    "R7 (medium): Dict-shape used for JSON-serialized payloads (comms.log); dataclass breaks JSON layer - mitigated by to_dict() + from_dict() methods on the dataclass"
  ],
  "out_of_scope": [
    "Modifications to src/code_path_audit*.py (the audit infrastructure is correct)",
    "The 4 NG1 + 7 NG2 audit violations (already addressed in dc397db7)",
    "The 4.01e22's nil-check component (per SSDL post-mortem; minor contributor)",
    "The RAG test pre-existing flake (per docs/reports/SSDL_CAMPAIGN_ABORTED_20260624.md Out of Scope)",
    "New src/<thing>.py files (per AGENTS.md hard rule; the dataclass goes in src/type_aliases.py)",
    "The 5 sub-aggregates becoming separate dataclasses each (overkill; they share the same Metadata base)"
  ]
}