archive completed or outdated tracks.

This commit is contained in:
ed
2026-06-12 20:41:31 -04:00
parent 20b1a1048e
commit b0f31a84bd
40 changed files with 0 additions and 0 deletions
@@ -0,0 +1,64 @@
{
"track_id": "docs_sync_test_era_20260610",
"name": "Test-Era Docs Sync (2026-06-10)",
"created_at": "2026-06-10",
"status": "shipped",
"priority": "A",
"blocked_by": [],
"blocks": [
"qwen_llama_grok_integration_20260606",
"data_oriented_error_handling_20260606",
"data_structure_strengthening_20260606",
"mcp_architecture_refactor_20260606",
"code_path_audit_20260607"
],
"inherits_from": [
"docs/reports/test_infrastructure_hardening_batch_green_20260610.md",
"docs/reports/test_bed_health_20260609.md"
],
"domain": "Documentation (Tier 1 chore, not implementation)",
"scope_summary": "End-state cleanup of 4 test-hell lineage tracks + full docs sync of 11 drift files against git diff baseline f93dac7d (2026-06-02 docs refresh) + durable lessons capture (1 new styleguide, 2 doc additions).",
"estimated_effort": "~90-120 minutes (actual: ~2 hours)",
"phases": 4,
"verification_criteria": [
"All 11 doc files with drift fixed (DONE)",
"4 test-hell tracks archived (DONE)",
"conductor/archive/ directory verified to exist (DONE; pre-existing)",
"tracks.md row 1 moved from Active to Archived (DONE); rows 2-5, 17 blocked_by updated to '(merged)' (DONE)",
"1 new styleguide created: conductor/code_styleguides/chroma_cache.md (DONE)",
"3 lessons added to conductor/workflow.md (DONE: HARD BAN, push_event race, async setters)",
"1 lesson added to conductor/product-guidelines.md (DONE: Testing Requirements section with Isolated-Pass Verification Fallacy)",
"All 4 audit scripts: 0 new violations (DONE; pre-existing findings unrelated)",
"Closing report at docs/reports/docs_sync_test_era_20260610.md (DONE)"
],
"out_of_scope": [
"Other 'Active' tracks (manual_ux_validation_20260608, ui_polish_five_issues, gencpp_dogfood_feedback_20260510) — not test-hell lineage",
"Migrating any source code",
"Creating new audit scripts",
"qwen_llama_grok planning (separate session)",
"Code-path audit (already on backlog)",
"The 9 pre-existing check_test_toml_paths.py false-positives in test mock content",
"The 7 pre-existing weak-type findings in src/log_registry.py"
],
"commit_count": 17,
"commit_list": [
"d82153c0 docs(models): sync WorkspaceProfile dataclass to 4-field model",
"7f58f980 docs(readme): fix WorkspaceProfile description + gui_2 line refs",
"f973fb27 docs(workspace_profiles): fix WorkspaceProfile schema",
"5aa19e59 docs(rag): sync with src/rag_engine.py",
"c5010356 docs(gui_2): __getattr__ hasattr-guard + startup architecture section",
"ca48d33d docs(simulations): update live_gui fixture signature",
"07c1ed49 docs(ai_client+api_hooks): lazy-loading + warmup endpoints",
"5fa8a10e docs(testing): critical live_gui_workspace path fix + 8 new sections",
"2e12b266 docs(mcp_client+ai_client): correct tool counts",
"237f5725 docs(app_controller): replace fictional __init__ + register_hooks",
"1ea38ad1 conductor(track): close 4 test-hell lineage tracks",
"5d262452 conductor(archive): move 4 test-hell tracks to archive/",
"3945fe37 conductor(tracks): archive test_infrastructure_hardening_20260609",
"f0b7c8b7 conductor(index): add Test Infrastructure Hardening to Recently Shipped",
"01ea22fc docs(styleguide): add chroma_cache.md",
"965e0157 docs(workflow): add 3 test-hell lessons",
"72b23745 docs(guidelines): add Testing Requirements section",
"aa7cdce8 docs(report): docs_sync_test_era_20260610 - closing report"
]
}
@@ -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
@@ -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)
@@ -0,0 +1,78 @@
# Track state for docs_sync_test_era_20260610
# Updated by Tier 1 as tasks complete
[meta]
track_id = "docs_sync_test_era_20260610"
name = "Test-Era Docs Sync (2026-06-10)"
status = "completed"
current_phase = 4
last_updated = "2026-06-10"
[blocked_by]
# No blockers; this is a Tier 1 chore
[blocks]
qwen_llama_grok_integration_20260606 = "ready (unblocked)"
data_oriented_error_handling_20260606 = "ready (unblocked)"
data_structure_strengthening_20260606 = "ready (unblocked)"
mcp_architecture_refactor_20260606 = "ready (unblocked)"
code_path_audit_20260607 = "ready (unblocked)"
[phases]
phase_1 = { status = "completed", checkpointsha = "237f5725", name = "Doc drift fixes (11 files)" }
phase_2 = { status = "completed", checkpointsha = "f0b7c8b7", name = "End-state cleanup (4 tracks archived)" }
phase_3 = { status = "completed", checkpointsha = "72b23745", name = "Lessons capture (1 styleguide + 3 doc additions)" }
phase_4 = { status = "completed", checkpointsha = "aa7cdce8", name = "Verify + closing report" }
[tasks]
# Phase 1: Doc drift fixes
t1_1 = { status = "completed", commit_sha = "f973fb27", description = "guide_workspace_profiles.md: WorkspaceProfile schema (4 critical)" }
t1_2 = { status = "completed", commit_sha = "d82153c0", description = "guide_models.md: WorkspaceProfile dataclass + remove LayoutPreset" }
t1_3 = { status = "completed", commit_sha = "5aa19e59", description = "guide_rag.md: collection attr, chroma path, dim validation, CWD fallback" }
t1_4 = { status = "completed", commit_sha = "c5010356", description = "guide_gui_2.md: __getattr__ fix, warmup, lazy imports, refresh rate" }
t1_5 = { status = "completed", commit_sha = "ca48d33d", description = "guide_simulations.md: live_gui fixture signature" }
t1_6 = { status = "completed", commit_sha = "07c1ed49", description = "guide_ai_client.md: _require_warmed lazy-loading pattern" }
t1_7 = { status = "completed", commit_sha = "07c1ed49", description = "guide_api_hooks.md: 4 warmup endpoints + 3 client methods (same commit as t1_6)" }
t1_8 = { status = "completed", commit_sha = "5fa8a10e", description = "guide_testing.md: live_gui_workspace path + 7 missing sections" }
t1_9 = { status = "completed", commit_sha = "2e12b266", description = "guide_mcp_client.md: tool counts 15->18, 45->46" }
t1_10 = { status = "completed", commit_sha = "7f58f980", description = "Readme.md: line refs in guide_gui_2 index" }
t1_11 = { status = "completed", commit_sha = "237f5725", description = "guide_app_controller.md: Architecture section (fictional AppState + register_hooks)" }
# Phase 2: End-state cleanup
t2_1 = { status = "completed", commit_sha = "5d262452", description = "conductor/archive/ already existed (71+ prior archived tracks); verified via Test-Path" }
t2_2 = { status = "completed", commit_sha = "1ea38ad1", description = "Close test_infrastructure_hardening_20260609 (state.toml + metadata.json)" }
t2_3 = { status = "completed", commit_sha = "1ea38ad1", description = "Close mma_tier_usage_reset_fix_20260610 (metadata.json)" }
t2_4 = { status = "completed", commit_sha = "1ea38ad1", description = "Close rag_phase4_sync_fix_20260610 (metadata.json)" }
t2_5 = { status = "completed", commit_sha = "1ea38ad1", description = "Close workspace_path_finalize_20260609 (state.toml + metadata.json)" }
t2_6a = { status = "completed", commit_sha = "5d262452", description = "git mv test_infrastructure_hardening_20260609 to archive/" }
t2_6b = { status = "completed", commit_sha = "5d262452", description = "git mv mma_tier_usage_reset_fix_20260610 to archive/" }
t2_6c = { status = "completed", commit_sha = "5d262452", description = "git mv rag_phase4_sync_fix_20260610 to archive/" }
t2_6d = { status = "completed", commit_sha = "5d262452", description = "git mv workspace_path_finalize_20260609 to archive/" }
t2_7 = { status = "completed", commit_sha = "3945fe37", description = "tracks.md: move row 1, update rows 2-5 blocked_by" }
t2_8 = { status = "completed", commit_sha = "f0b7c8b7", description = "index.md: add Recently Shipped entry" }
# Phase 3: Lessons capture
t3_1 = { status = "completed", commit_sha = "01ea22fc", description = "New styleguide: conductor/code_styleguides/chroma_cache.md" }
t3_2 = { status = "completed", commit_sha = "965e0157", description = "workflow.md: 3 lessons (HARD BAN, push_event race, async setters)" }
t3_3 = { status = "completed", commit_sha = "72b23745", description = "product-guidelines.md: Testing Requirements section with Isolated-Pass Verification Fallacy" }
# Phase 4: Verify
t4_1 = { status = "completed", commit_sha = "aa7cdce8", description = "Run 4 audit scripts; 0 new violations (pre-existing findings are unrelated)" }
t4_2 = { status = "completed", commit_sha = "aa7cdce8", description = "Spot-check cross-links: 4 Test-Path verifications + tracks.md/index.md link resolution" }
t4_3 = { status = "completed", commit_sha = "aa7cdce8", description = "Write closing report docs/reports/docs_sync_test_era_20260610.md" }
[verification]
phase_1_docs_synced = true
phase_2_tracks_archived = true
phase_3_lessons_captured = true
phase_4_verified_and_reported = true
all_audit_scripts_zero_new_violations = true
all_4_tracks_archived_to_conductor_archive = true
all_11_doc_files_with_drift_fixed = true
1_new_styleguide_created_chroma_cache = true
4_lessons_placed_in_durable_locations = true
[closure_notes]
# Closed by Tier 1 (MiniMax-M3) on 2026-06-10
# 17 atomic commits across 4 phases. Closing report: docs/reports/docs_sync_test_era_20260610.md
# Next Tier 2 engaging qwen_llama_grok_integration_20260606 has pristine context.