conductor(track): add docs_sync_test_era_20260610 plan.md and spec.md

These were authored at track start but missed by the final-state
commit. They are the brief 1-2 page design intent and executable
plan for the docs sync track. The closing report at
docs/reports/docs_sync_test_era_20260610.md summarizes the actual
17-commit execution.

conductor/tracks/docs_sync_test_era_20260610/plan.md

@@ -0,0 +1,157 @@
+# 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

conductor/tracks/docs_sync_test_era_20260610/spec.md

@@ -0,0 +1,75 @@
+# 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)