# Track Specification: Test-Era Docs Sync (2026-06-10)

## Overview
End-state cleanup and full docs sync following the 4-day test-hell saga (regression_fixes → test_infrastructure_hardening → mma_tier_usage_reset_fix → rag_phase4_sync_fix → workspace_path_finalize). Goal: the next Tier 2 agent engaging `qwen_llama_grok_integration_20260606` has pristine, drift-free docs to read.

## Current State Audit (as of 2026-06-10, baseline `f93dac7d`)

### Code deltas since 2026-06-02 docs refresh
- `src/app_controller.py` — 4 mma_tier_usage/flush_to_project/LazyManager bug fixes
- `src/rag_engine.py` — rag_config reset, _validate_collection_dim (dim-mismatch recursion), embedding init error status, CWD fallback in index_file
- `src/gui_2.py` — __getattr__ fix (silent-None bug from bcdc26d0), warmup infrastructure
- `src/ai_client.py` — _require_warmed lazy-loading refactor (8 commits)
- `src/api_hooks.py` — /api/warmup_status, /api/warmup_wait, /api/warmup_canaries, /api/startup_timeline endpoints
- `src/workspace_manager.py` — WorkspaceProfile ini_content str-vs-bytes contract
- `src/simulation/sim_context.py` — defensive setdefault('paths', [])
- `tests/conftest.py` — _LiveGuiHandle, _check_live_gui_health, live_gui_workspace, _reset_clean_baseline, xdist O_EXCL mutex, watchdog 600s/900s
- `pyproject.toml` — clean_baseline marker, watchdog timeout
- `scripts/` — audit_main_thread_imports.py, audit_weak_types.py, run_tests_batched.py (tier-based)

### Already done (no action)
- `docs/guide_testing.md` was updated 6/9 5:03 PM (commit `cb525519`) — covers _LiveGuiHandle + live_gui_workspace + clean_baseline marker
- `docs/reports/test_bed_health_20260609.md` and `docs/reports/test_infrastructure_hardening_batch_green_20260610.md` are committed
- `conductor/code_styleguides/workspace_paths.md` was added 6/9
- 3 of 6 lessons are already in `AGENTS.md` Process Anti-Patterns

### Gaps to fill (this track's scope)
**20 critical, 21 moderate, 12 minor drift items** across 11 doc files (full inventory in track plan §"Audit Findings").

**End-state cleanup:**
- 4 track folders in `conductor/tracks/` need archiving: test_infrastructure_hardening_20260609, mma_tier_usage_reset_fix_20260610, rag_phase4_sync_fix_20260610, workspace_path_finalize_20260609
- 1 `conductor/archive/` directory needs to be created (does not exist on disk)
- 4 `state.toml` files need `status`/`last_updated` updates
- 4 `metadata.json` files need `status: spec` → `status: shipped`
- `conductor/tracks.md` row 1 needs to move from Active to Archived
- `conductor/index.md` "Recently Shipped" needs new entry

**Lessons capture:**
- Lesson 5 (chroma cache path) → new `conductor/code_styleguides/chroma_cache.md`
- Lessons 1, 2, 3, 6 → additions to `conductor/product-guidelines.md` and `conductor/workflow.md`

## Goals
1. All 11 doc files with drift fixed to match current `src/` behavior
2. All 4 test-hell lineage tracks properly archived with consistent state
3. 4 lessons placed in durable locations (1 new styleguide + 2 file additions)
4. `tracks.md` + `index.md` reflect the new archive reality
5. All audit scripts still report 0 regressions
6. Total time: ~90-120 min

## Functional Requirements
- Doc edits must be grounded in `git diff` against baseline `f93dac7d`
- Doc edits must use `manual-slop_edit_file` for surgical precision (no native `edit`)
- Each doc file gets at most 1 atomic commit (multiple drift items in one commit per file)
- `conductor/tracks.md` row 1 must move to a "Late June 2026: Test Infrastructure Hardening" archived section
- `conductor/archive/` must be created (the 71 archive links in tracks.md have never been populated)

## Non-Functional Requirements
- No new audit violations (existing audit scripts must still report 0)
- No scope creep: only the 11 drift files + 4 tracks + lessons files are in scope
- All changes must follow the project's 1-space indentation for any Python touched (none expected)
- Each commit message ≤ 15 lines (per AGENTS.md "Verbose-Commit-Message" rule)

## Architecture Reference
- `docs/guide_architecture.md` — Threading model, event system, AI client multi-provider
- `docs/guide_app_controller.md` — Controller state, managers, Hook API
- `docs/guide_rag.md` — RAG engine, vector store, embedding providers
- `docs/guide_gui_2.md` — App class, render functions, hot reload
- `docs/guide_testing.md` — Conftest fixtures, live_gui pattern, audit scripts
- `docs/Readme.md` — Docs index (30 guides)

## Out of Scope
- Other "Active" tracks (manual_ux_validation_20260608, ui_polish_five_issues, gencpp_dogfood_feedback_20260510, etc.) — these are not test-hell lineage
- Migrating any source code
- Creating new audit scripts
- `qwen_llama_grok` planning — separate session
- Code-path audit (already on the backlog)
