diff --git a/conductor/tracks/docs_sync_test_era_20260610/plan.md b/conductor/tracks/docs_sync_test_era_20260610/plan.md new file mode 100644 index 00000000..9764b4cb --- /dev/null +++ b/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_/` +- 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_` +- 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 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_/` +- 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 -- ` 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 diff --git a/conductor/tracks/docs_sync_test_era_20260610/spec.md b/conductor/tracks/docs_sync_test_era_20260610/spec.md new file mode 100644 index 00000000..8494608a --- /dev/null +++ b/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)