{
  "track_id": "test_batching_refactor_20260606",
  "name": "Test Batching Refactor",
  "initialized": "2026-06-06",
  "owner": "tier2-tech-lead",
  "priority": "medium",
  "status": "active",
  "type": "developer tooling + diagnostic improvement",
  "scope": {
    "new_files": [
      "scripts/test_categorizer.py",
      "scripts/test_batcher.py",
      "scripts/pytest_collection_order.py",
      "tests/test_categories.toml",
      "tests/test_categorizer.py",
      "tests/test_batcher.py"
    ],
    "modified_files": [
      "scripts/run_tests_batched.py",
      "tests/conftest.py",
      "pyproject.toml"
    ],
    "deleted_files_at_phase4": [
      "scripts/run_tests_batched.py.legacy"
    ]
  },
  "blocked_by": [],
  "blocks": [],
  "estimated_phases": 4,
  "spec": "spec.md",
  "plan": "plan.md",
  "priority_order": "B (process isolation by fixture class) > A (subsystem diagnostic grouping) > C (xdist + live_gui session reuse)",
  "tier_model": {
    "0_opt_in": "test_clean_install.py, test_docker_build.py; one batch per file; runs only if env var set AND --include-opt-in passed",
    "1_unit": "Pure unit tests (no live_gui/mock_app/app_instance); grouped by batch_group; pytest-xdist -n auto",
    "2_mock_app": "Tests using mock_app or app_instance fixtures; grouped by batch_group; no xdist",
    "3_live_gui": "All tests using live_gui fixture in ONE pytest invocation (session-scoped reuse)",
    "H_headless": "Headless service tests; one pytest invocation",
    "P_performance": "Performance/stress tests; runs last; one pytest invocation"
  },
  "hybrid_classification": "Auto-infer by default from filename and AST fixture scan; tests/test_categories.toml provides hand-curated overrides for cross-cutting and ambiguous files. Registry always wins precedence.",
  "architectural_invariant": "Every pytest subprocess invocation has a single, well-defined fixture profile. live_gui tests never share a pytest process with non-live_gui tests. Opt-in tests are gated on BOTH env var AND --include-opt-in CLI flag (defense in depth).",
  "cli_surface": {
    "default": "All tiers except opt-in (0) and performance (P); xdist enabled for tier 1",
    "--tiers": "Comma-separated tier list to include (e.g. --tiers 1,2,3)",
    "--include-opt-in": "Hard flag required IN ADDITION to env var to run opt-in tests",
    "--plan": "Dry-run; print batch plan and exit",
    "--audit": "List auto-inferred (unclassified) files; exit non-zero on hard errors",
    "--no-xdist": "Disable pytest-xdist for tier 1 (debug aid)",
    "--strict-markers": "Pass --strict-markers to pytest (catch marker typos)"
  },
  "verification_criteria": [
    "scripts/test_categorizer.py::categorize_all returns 277+ CategoryRecords with no exceptions",
    "scripts/test_batcher.py::plan is deterministic (same inputs -> same outputs)",
    "All 277+ test files are correctly classified: live_gui / mock_app / unit / opt_in / performance",
    "Cross-cutting files (test_gui_dag_beads, test_arch_boundary_phase*, etc.) are flagged with multiple subsystems in the report",
    "--plan output matches the existing 4-at-a-time batching modulo opt-in gating",
    "No live_gui test ever runs in the same pytest invocation as a non-live_gui test",
    "Opt-in tests are skipped silently when env var is not set (no warning, no error)",
    "Opt-in tests are skipped silently when --include-opt-in is not passed (env var alone is insufficient)",
    "scripts/check_test_toml_paths.py still exits 0 (no real TOML references in tests)",
    "Existing 273+ test suite passes when run via the new script in --tiers 1,2,3 mode",
    "tests/test_categorizer.py and tests/test_batcher.py pass with >80% coverage",
    "pytest_collection_order plugin is a no-op when no [[test_order]] entries exist (zero overhead)"
  ],
  "links": {
    "backlog_entry": "conductor/tracks.md (to be added at top of Remaining Backlog)",
    "current_script": "scripts/run_tests_batched.py",
    "testing_guide": "docs/guide_testing.md",
    "workflow_pitfalls": "conductor/workflow.md#known-pitfalls-2026-06-05",
    "related_tracks": [
      "conductor/tracks/startup_speedup_20260606/",
      "conductor/tracks/regression_fixes_20260605/",
      "conductor/tracks/live_gui_test_hardening_v2_20260605/"
    ]
  }
}
