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

> Tier 1 execution plan. Sequential phases. Per-file atomic commits.

## Phase 1: Doc drift fixes (highest priority)

Each task: read current text → apply surgical fix via `manual-slop_edit_file` → commit.

### Task 1.1: `docs/guide_workspace_profiles.md` — 4 critical schema drifts
- Rename `docking_layout` → `ini_content` throughout (4+ occurrences)
- Rename `window_visibility` → `show_windows`
- Rename `panel_state` → `panel_states` (plural)
- Update TOML example to use `ini_content = "..."` (plain string, not BASE64)
- Commit: `docs(workspace_profiles): fix WorkspaceProfile schema fields to match src/workspace_manager.py`

### Task 1.2: `docs/guide_models.md` — WorkspaceProfile dataclass drift
- Update `WorkspaceProfile` definition to use `ini_content`, `show_windows`, `panel_states`
- Remove non-existent `LayoutPreset` reference
- Commit: `docs(models): fix WorkspaceProfile schema in guide_models.md`

### Task 1.3: `docs/guide_rag.md` — 2 critical + 3 moderate + 2 minor drifts
- Replace `vector_store` → `collection` (all occurrences)
- Replace `vector_store_backend` → `provider` in RAGConfig schema
- Replace `.rag/chroma/` → `.slop_cache/chroma_<collection_name>/`
- Remove "falls back to dummy embeddings" text (now raises ImportError)
- Add §"Dimension Mismatch Protection" describing `_validate_collection_dim`
- Add CWD fallback note to `index_file` description
- Commit: `docs(rag): sync with src/rag_engine.py (collection attr, chroma path, dim validation, CWD fallback)`

### Task 1.4: `docs/guide_gui_2.md` — 1 critical + 4 moderate + 3 minor drifts
- Update `__getattr__` code example to fixed version with `hasattr` guard
- Add section on `_LazyModule` / `_FiledialogStub` lazy imports
- Add section on `startup_profiler` integration + `render_warmup_status_indicator`
- Add section on native `_detect_refresh_rate_win32` (ctypes.EnumDisplaySettingsW)
- Add `immapp.run` try/except error handling note
- Update line numbers for `_capture_workspace_profile` (now at ~813)
- Commit: `docs(gui_2): sync with __getattr__ fix, warmup infra, lazy imports`

### Task 1.5: `docs/guide_simulations.md` — 2 critical drifts
- Update `live_gui` fixture signature: `Generator[tuple[...], ...]` → `Generator["_LiveGuiHandle", ...]`
- Update yield description to describe `_LiveGuiHandle` (.process, .gui_script, .workspace, .is_alive())
- Commit: `docs(simulations): update live_gui fixture signature to _LiveGuiHandle`

### Task 1.6: `docs/guide_ai_client.md` — 2 critical drifts
- Document `_require_warmed` lazy-loading pattern from `src.module_loader`
- Update Per-Provider State section to note clients are obtained lazily
- Commit: `docs(ai_client): document _require_warmed lazy-loading pattern`

### Task 1.7: `docs/guide_api_hooks.md` — 2 critical + 1 moderate drifts
- Add 4 warmup endpoints to endpoints table: /api/warmup_status, /api/warmup_wait, /api/warmup_canaries, /api/startup_timeline
- Add "Warmup API" section: get_warmup_status(), get_warmup_wait(timeout), get_warmup_canaries() client methods
- Add `get_warmup_wait()` to External Script Pattern example
- Commit: `docs(api_hooks): document 4 warmup endpoints + 3 client methods`

### Task 1.8: `docs/guide_testing.md` — 1 critical + 6 missing sections
- **CRITICAL**: Fix `tmp_path_factory` text on line 229 — actually uses `tests/artifacts/live_gui_workspace_<timestamp>`
- Add §"Watchdog and Hang Bounding" (600s smart, 900s unconditional)
- Add §"Chroma Cache Path and Cross-Test Pollution"
- Add §"xdist Worker Coordination and Stale Lock Demotion"
- Expand §"Audit Scripts" with `audit_main_thread_imports.py` + `audit_weak_types.py`
- Add §"Required Test Dependencies Gate" (sentence-transformers, `uv sync --extra local-rag`)
- Add §"MMA and RAG State in reset_session" (mma_tier_usage, mma_status, active_tier, rag_engine, rag_config)
- Add `__getitem__` to _LiveGuiHandle table (handle[0], handle[1])
- Commit: `docs(testing): add 7 missing sections (watchdog, chroma, xdist, audit, deps, reset, indexing)`

### Task 1.9: `docs/guide_mcp_client.md` — 2 moderate drifts
- Fix Python AST Tools count: `(15)` → `(19)`
- Fix total tool count: `45` → `46`
- Commit: `docs(mcp_client): correct tool counts (Python AST 15→19, total 45→46)`

### Task 1.10: `docs/Readme.md` — 1 critical + 1 moderate
- Update line refs in `guide_gui_2.md` index entry
- Verify all 30 guides are indexed (none missing/extra)
- Commit: `docs(readme): update line refs in guide_gui_2 index entry`

## Phase 2: End-state cleanup

### Task 2.1: Create `conductor/archive/` directory
- Test-Path first to verify parent exists
- New-Item -ItemType Directory -Path "C:\projects\manual_slop\conductor\archive"
- This is a separate commit: `conductor(archive): create archive/ directory (was referenced but never existed)`

### Task 2.2: Update `test_infrastructure_hardening_20260609` end-state
- `state.toml`: status "active" → "completed"; last_updated "2026-06-09" → "2026-06-10"
- Mark t7_1_*, t7_2_*, t8_1_*, t8_2_* tasks as `status = "completed"` with commit SHAs from batch-green report
- `metadata.json`: status "spec" → "shipped"
- Commit: `conductor(track): close test_infrastructure_hardening_20260609`

### Task 2.3: Update `mma_tier_usage_reset_fix_20260610` end-state
- `metadata.json`: status "spec" → "shipped"
- Commit: `conductor(track): close mma_tier_usage_reset_fix_20260610`

### Task 2.4: Update `rag_phase4_sync_fix_20260610` end-state
- `metadata.json`: status "spec" → "shipped"
- Commit: `conductor(track): close rag_phase4_sync_fix_20260610`

### Task 2.5: Update `workspace_path_finalize_20260609` end-state
- `state.toml`: status "active" → "completed"; current_phase 1 → "complete"
- `metadata.json`: status "spec" → "shipped"
- Commit: `conductor(track): close workspace_path_finalize_20260609`

### Task 2.6: Move 4 track folders to `archive/`
- `git mv` each folder
- 1 commit per folder (4 commits): `conductor(archive): move <track_id> to archive/`

### Task 2.7: Update `conductor/tracks.md`
- Move row 1 (Test Infrastructure Hardening) from Active Tracks table to new "Late June 2026: Test Infrastructure Hardening" archived section
- Update blocked_by on rows 2-5: `test_infrastructure_hardening_20260609` → `merged`
- Commit: `conductor(tracks): archive 4 test-hell tracks; update blocked_by`

### Task 2.8: Update `conductor/index.md`
- Add "Recently Shipped: Test Infrastructure Hardening (2026-06-10)" entry
- Commit: `conductor(index): add Test Infrastructure Hardening to Recently Shipped`

## Phase 3: Lessons capture

### Task 3.1: New styleguide `conductor/code_styleguides/chroma_cache.md`
- Document exact path: `tests/artifacts/.slop_cache/chroma_<project>/`
- Document why: trailing-slash `parent` bug
- Document the cleanup pattern used in RAG tests
- Commit: `docs(styleguide): add chroma_cache.md — chroma DB path and cleanup pattern`

### Task 3.2: `conductor/workflow.md` — add 3 lessons
- Add HARD BAN: `git checkout -- <file>` to Known Pitfalls section
- Add `push_event` + `time.sleep` + `assert` race rule to Live_gui Test Fragility
- Add async setters poll-for-state rule to Live_gui Test Fragility
- Commit: `docs(workflow): add 3 test-hell lessons to Known Pitfalls + Live_gui Test Fragility`

### Task 3.3: `conductor/product-guidelines.md` — add 1 lesson
- Add "Isolated-Pass Verification Fallacy" under Testing Requirements
- Commit: `docs(guidelines): add Isolated-Pass Verification Fallacy to Testing Requirements`

## Phase 4: Verify

### Task 4.1: Run audit scripts
- `uv run python scripts/audit_main_thread_imports.py`
- `uv run python scripts/audit_weak_types.py`
- `uv run python scripts/check_test_toml_paths.py`
- All must report 0 new violations

### Task 4.2: Spot-check cross-links
- Verify each guide cross-link resolves
- Verify Readme.md index points to all 30 guides

### Task 4.3: Write closing report
- `docs/reports/docs_sync_test_era_20260610.md`
- Summarize what was fixed, lessons placed, tracks archived
- Commit: `docs(report): docs_sync_test_era_20260610 — closing report`

## Verification
- [ ] All 11 drift doc files have committed fixes
- [ ] All 4 test-hell tracks archived
- [ ] `tracks.md` row 1 moved; rows 2-5 blocked_by updated
- [ ] 1 new styleguide created; 2 doc files updated with lessons
- [ ] All audit scripts report 0 violations
- [ ] Closing report committed
- [ ] All per-file commits ≤ 15 lines commit message
