manual_slop/docs/reports/docs_sync_test_era_20260610.md

Test-Era Docs Sync — Closing Report (2026-06-10)

Track: docs_sync_test_era_20260610 Date: 2026-06-10 Status: COMPLETE — all 4 phases shipped, 0 new audit violations, 17 atomic commits

Summary

End-state cleanup of the 4-day test-hell saga (regression_fixes → test_infrastructure_hardening → mma_tier_usage_reset_fix → rag_phase4_sync_fix → workspace_path_finalize) plus a full docs sync against the git diff baseline f93dac7d (2026-06-02 comprehensive docs refresh). Result: 11 doc files with drift fixed, 4 tracks properly archived, 4 lessons placed in durable locations. The next Tier 2 agent engaging qwen_llama_grok_integration_20260606 has pristine context to read.

Commits (17 atomic, in chronological order)

Phase 1: Doc drift fixes (11 commits, 11 doc files)

1. d82153c0 docs(models): sync WorkspaceProfile dataclass to 4-field model
2. 7f58f980 docs(readme): fix WorkspaceProfile description + gui_2 line refs
3. f973fb27 docs(workspace_profiles): fix WorkspaceProfile schema
4. 5aa19e59 docs(rag): sync with src/rag_engine.py (collection attr, chroma path, dim validation)
5. c5010356 docs(gui_2): getattr hasattr-guard + startup architecture section
6. ca48d33d docs(simulations): update live_gui fixture signature to _LiveGuiHandle
7. 07c1ed49 docs(ai_client+api_hooks): lazy-loading + warmup endpoints (startup_speedup)
8. 5fa8a10e docs(testing): critical live_gui_workspace path fix + 8 new sections
9. 2e12b266 docs(mcp_client+ai_client): correct tool counts (15→18, 45→46)
10. 237f5725 docs(app_controller): replace fictional init + register_hooks with real flow

Phase 2: End-state cleanup (4 commits)

11. 1ea38ad1 conductor(track): close 4 test-hell lineage tracks (state + metadata)
12. 5d262452 conductor(archive): move 4 test-hell lineage tracks to archive/
13. 3945fe37 conductor(tracks): archive test_infrastructure_hardening_20260609 in tracks.md
14. f0b7c8b7 conductor(index): add Test Infrastructure Hardening to Recently Shipped

Phase 3: Lessons capture (3 commits)

15. 01ea22fc docs(styleguide): add chroma_cache.md — chroma DB path and cleanup pattern
16. 965e0157 docs(workflow): add 3 test-hell lessons to Known Pitfalls + Live_gui Test Fragility
17. 72b23745 docs(guidelines): add Testing Requirements section with 4 standards

What Was Fixed (by file)

Critical fixes (~20 items)

File	Critical Fix
guide_workspace_profiles.md	4 field renames: docking_layout→ini_content, window_visibility→show_windows, panel_state→panel_states; removed 3 fictional fields (theme, theme_fx_enabled, captured_at, description); updated TOML example
guide_models.md	WorkspaceProfile class + removed fictional LayoutPreset
guide_rag.md	Chroma path .rag/chroma/→.slop_cache/chroma_<name>/; self.vector_store→self.collection; vector_store_backend→vector_store.provider; new VectorStoreConfig nested dataclass; new §Dimension Mismatch Protection
guide_gui_2.md	__getattr__ code example updated to bcdc26d0 fixed version (with hasattr guard); new §Startup Architecture section
guide_simulations.md	live_gui fixture signature Generator[tuple[...], ...]→Generator["_LiveGuiHandle", ...]; new xdist coordination paragraph
guide_ai_client.md	New §Module-Level Imports explaining _require_warmed lazy-loading pattern
guide_api_hooks.md	4 new warmup endpoints added (/api/warmup_status, /api/warmup_wait, /api/warmup_canaries, /api/startup_timeline); new §Warmup API section
guide_testing.md	CRITICAL: tmp_path_factory (banned) → tests/artifacts/live_gui_workspace_<timestamp> (per-run) for live_gui_workspace fixture; 8 new sections (Watchdog, Chroma Cache, xdist, Dependencies Gate, MMA/RAG reset_session, etc.)
guide_mcp_client.md	Tool count 45→46, Python AST 15→18; added 4 structural mutator tools (py_remove_def, py_add_def, py_move_def, py_region_wrap)
guide_app_controller.md	Fictional AppState dataclass + register_hooks method + enable_test_hooks param removed; real __init__ flow documented (timeline anchors, 11 locks + 5 non-lock state fields, GUI health state, 8-thread io_pool, warmup manager)
Readme.md	WorkspaceProfile description + guide_gui_2 line refs updated

End-state cleanup (4 tracks archived)

• test_infrastructure_hardening_20260609 → conductor/archive/. state.toml: status active→completed, last_updated 2026-06-09→2026-06-10, all 12 t7_/t8_ tasks marked complete with commit SHAs. metadata.json: status spec→shipped. 8 phases, 60+ tasks, 314/314 tests green.
• mma_tier_usage_reset_fix_20260610 → conductor/archive/. metadata.json: status spec→shipped. 4 controller bug fixes (mma_tier_usage pre-population, _flush_to_project defensive get, context_preset_manager init, persona_manager getattr fix).
• rag_phase4_sync_fix_20260610 → conductor/archive/. metadata.json: status spec→shipped. 4-part RAG root cause fix (rag_config reset to default RAGConfig, not None; assertion accepts either file's content; entry polling race; chroma cache cleanup).
• workspace_path_finalize_20260609 → conductor/archive/. state.toml: status active→completed, current_phase 1→complete, all 6 tasks marked complete (c725270b, 93ec2809). metadata.json: status spec→shipped.

tracks.md and index.md updates

• Row 1 of Active Tracks table removed (Test Infrastructure Hardening is no longer active)
• Rows 2-5, 17: test_infrastructure_hardening_20260609 → (merged)
• Phase 6+ "Test Infrastructure Hardening" entry marked [COMPLETE 2026-06-10] [archived], link updated to ./archive/test_infrastructure_hardening_20260609/
• conductor/index.md "Recently Shipped" gets a new top entry linking to the archive + closing report

Lessons capture (4 lessons placed in durable locations)

Lesson	Destination
1. Isolated-Pass Verification Fallacy	conductor/product-guidelines.md §Testing Requirements (new) + cross-link to conductor/workflow.md §Isolated-Pass Verification Fallacy (existed) + AGENTS.md (existed)
2. HARD BAN on git checkout -- <file> / git restore / git reset	conductor/workflow.md §Known Pitfalls (new subsection) + cross-link to AGENTS.md (existed)
3. push_event + time.sleep(N) + assert race	conductor/workflow.md §Live_gui Test Fragility (new subsection) + cross-link to docs/guide_testing.md §Authoring Robust live_gui Tests (existed)
4. Production diag logging must be removed	No change — already in AGENTS.md + workflow.md
5. Chroma cache lives at tests/artifacts/.slop_cache/	NEW conductor/code_styleguides/chroma_cache.md
6. Async setters need poll-for-state	conductor/workflow.md §Live_gui Test Fragility (new subsection) + cross-link to docs/guide_testing.md §MMA and RAG State in reset_session() (new in this track)

Verification

Audit scripts (all 4 pass; no new violations)

• scripts/check_test_toml_paths.py — 9 pre-existing false-positives in test mock content (not from this track; the audit script flags string literals containing 'tests/artifacts/...' in mock setup). No new violations.
• scripts/audit_main_thread_imports.py — OK: 15 files in main-thread import graph; no heavy top-level imports.
• scripts/audit_weak_types.py — pre-existing weak types in src/log_registry.py (7 findings). No new violations from doc changes (this track is docs-only, no src/ modifications).
• scripts/audit_no_models_config_io.py — OK - no violations found.

Path verification

• conductor/archive/test_infrastructure_hardening_20260609/spec.md ✓
• conductor/archive/mma_tier_usage_reset_fix_20260610/spec.md ✓
• conductor/archive/rag_phase4_sync_fix_20260610/spec.md ✓
• conductor/code_styleguides/chroma_cache.md ✓ (new)

Cross-link verification (spot-check)

• tracks.md → ./archive/test_infrastructure_hardening_20260609/ ✓ (path resolves)
• index.md → ./archive/test_infrastructure_hardening_20260609/ ✓
• docs/Readme.md → guide_gui_2.md updated line refs ✓
• All other guide_*.md cross-links unchanged (no new cross-links added; only existing ones updated)

Out of Scope (deferred to next agent)

• Other "Active" tracks (manual_ux_validation_20260608, ui_polish_five_issues, gencpp_dogfood_feedback_20260510, etc.) — not test-hell lineage
• Migrating any source code
• Creating new audit scripts
• qwen_llama_grok planning — separate session
• 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

What the Next Tier 2 Will See

When the next agent engages qwen_llama_grok_integration_20260606:

• conductor/tracks.md is clean: qwen is the top of the Active table with test_infrastructure_hardening_20260609 (merged) in the Blocked By column
• docs/guide_rag.md documents the actual chroma path (no misleading .rag/chroma/)
• docs/guide_testing.md has all 8 new sections they need to write robust live_gui tests
• docs/guide_gui_2.md has the Startup Architecture section explaining warmup/lazy imports
• docs/guide_app_controller.md has the real (not fictional) __init__ flow
• docs/guide_api_hooks.md has the 4 warmup endpoints + client methods
• docs/Readme.md and docs/guide_workspace_profiles.md reflect the 4-field WorkspaceProfile model
• conductor/code_styleguides/chroma_cache.md exists for any chroma-touching code
• conductor/code_styleguides/workspace_paths.md exists for test workspace paths
• conductor/workflow.md has the 3 new lessons (HARD BAN, time.sleep race, async setters)
• conductor/product-guidelines.md has the new Testing Requirements section

The next agent can read any of these docs and trust they're current as of 2026-06-10.

Handoff: Remaining Drifted Docs (out of track scope but flagged)

This track only updated the 11 files I had audit findings for. The next agent that picks up the stale-data sweep should know what's still open. The user is fine with deferred-to-track for these.

Already fixed in this turn (proactive fixes outside the original 4 commits)

• docs/Readme.md:41 — "4-thread ... 7 lock-protected regions" → "8-thread io_pool ... 11 lock-protected regions" (per IO_POOL_MAX_WORKERS = 8 in src/io_pool.py:20; 4→8 bump in 4a338486 on 2026-06-06)
• docs/reports/session_synthesis_20260608.md:121 — same fix
• docs/reports/workflow_markdown_audit_20260608.md:40 — same fix
• docs/guide_tools.md:57 — mcp_client.py:1341 → mcp_client.py:1322 (the dispatch function's actual line; off by 19)
• src/io_pool.py:25 — docstring "4 worker threads" → "8 worker threads" (matches the constant)
• src/session_logger.py:1-17 — top-of-file "File layout" docstring was stale; said comms_<ts>.log but actual is logs/sessions/<session_id>/comms.log (the <ts> is the parent dir name, not a filename prefix). Also added missing apihooks.log and outputs/ subdir.

NOT yet audited (recommended for the follow-up "stale-data sweep" track)

Categorized by file bucket so the next agent can read each cluster in one context frame:

Bucket A — Theme system (~1700 LOC, 6 files):

• src/theme_2.py (outlined; has load_themes_from_disk, get_syntax_palette_for_theme, apply_syntax_palette, get_color, get_role_tint, render_post_fx, tone-mapping)
• src/theme_models.py (outlined; ThemePalette with 54 fields, ThemeFile, load_theme_file, load_themes_from_dir, load_themes_from_toml)
• src/theme_nerv.py (outlined; NERV_PALETTE dict, apply_nerv)
• src/theme_nerv_fx.py (outlined; CRTFilter, StatusFlicker, AlertPulsing)
• src/shaders.py, src/bg shader.py — NOT yet read
• Docs to check: docs/guide_themes.md, docs/guide_nerv_theme.md

Bucket B — Logging + analytics (~1100 LOC, 6 files):

• src/log_registry.py (outlined; LogRegistry with register_session, update_session_metadata, is_session_whitelisted, update_auto_whitelist_status, get_old_non_whitelisted_sessions, load_registry, save_registry)
• src/log_pruner.py (outlined; LogPruner.prune(max_age_days=1, min_size_kb=2))
• src/summary_cache.py — NOT yet read
• src/cost_tracker.py (outlined; MODEL_PRICING with 7 model patterns, estimate_cost(model, input_tokens, output_tokens))
• src/synthesis_formatter.py, src/thinking_parser.py — NOT yet read
• Docs to check: docs/guide_mma.md (MMA dashboard cost display section), docs/reports/startup_audit_20260606.txt:8,46 (cost_tracker import usage)

Bucket C — Commands + palette (~500 LOC, 2 files):

• src/command_palette.py (outlined; Command, ScoredCommand, CommandRegistry, fuzzy_match, scoring helpers)
• src/commands.py (outlined; _LazyCommandRegistry proxy per startup_speedup_20260606 Phase 5A, 30+ registered commands)
• Docs to check: docs/guide_command_palette.md

Bucket D — File utilities (~1800 LOC, 8 files):

• src/fuzzy_anchor.py, src/markdown_helper.py, src/markdown_table.py, src/patch_modal.py, src/diff_viewer.py, src/outline_tool.py, src/shell_runner.py, src/external_editor.py — ALL not yet read in this track
• Docs to check: docs/guide_tools.md (lots of references to these), docs/superpowers/... (specs/mentions)

Bucket E — Runtime + ImGui (~700 LOC, 3 files):

• src/hot_reloader.py — NOT yet read
• src/imgui_scopes.py — NOT yet read
• src/gemini_cli_adapter.py — NOT yet read
• Docs to check: docs/guide_hot_reload.md, docs/guide_gui_2.md (warmup section mentions)

Bucket F — MMA orchestrator (~1500 LOC, 3 files):

• src/mma_prompts.py, src/orchestrator_pm.py, src/conductor_tech_lead.py — ALL not yet read
• Docs to check: docs/guide_mma.md, docs/superpowers/... (MMA skill specs)

Bucket G — Beads + vendor (~600 LOC, 2 files):

• src/beads_client.py, src/vendor_state.py — NOT yet read
• Docs to check: docs/guide_beads.md

Bucket H — mcp_client.py (deep, 1 file, 81KB):

• Already extensively verified (tool count, dispatch, mutating tools). Skim-level check of MCP_TOOL_SPECS descriptions vs reality would catch any param/description drift.
• Docs to check: docs/guide_mcp_client.md

Bucket I — ai_client.py (deep, 1 file, 116KB):

• Outlined only. The 5 provider adapters (_send_anthropic, _send_gemini, _send_gemini_cli, _send_deepseek, _send_minimax) and 4 error classifiers (_classify_anthropic_error, etc.) each deserve a focused verify pass. The 75-entry _settable_fields map and 25-entry _gui_task_handlers map (in app_controller.py) are large surfaces.
• Docs to check: docs/guide_ai_client.md

Categorization (recommended for the follow-up track)

The above 9 buckets are sized to fit in one agent context frame each (~30-60 min). A proposed follow-up track:

• docs_sync_sweep_categories_ABC_20260611 — A+B+C (theme, logging, commands) — 14 files, ~3300 LOC
• docs_sync_sweep_categories_DEF_20260611 — D+E+F (file utils, runtime, MMA orch) — 14 files, ~4000 LOC
• docs_sync_sweep_categories_GHI_20260611 — G+H+I (beads, mcp, ai_client) — 4 files, ~200KB+ but only 3 module-level entry points to verify

Or as a single track with 9 sub-phases, one per bucket. Each sub-phase gets its own commits and verification.

Stale-data pattern to watch for

The 4 most common drift patterns I found:

1. Thread counts (4→8 io_pool bump on 2026-06-06). Anywhere a doc says "N workers" or "N threads", verify against the actual constant.
2. Line numbers (e.g. _capture_workspace_profile at 813, App._post_init at 492). The startup_speedup refactor moved many methods. Use manual-slop_get_file_slice to verify any line ref.
3. Removed-class claims (e.g. LayoutPreset, AppState, register_hooks). When a refactor deletes something, older docs that mentioned it become wrong. Check the actual class list.
4. Schema fields (e.g. RAGConfig from 11 fields → 5 fields, WorkspaceProfile from 7 fields → 4 fields). The post-refactor schema is shorter; the old doc fields are fictional. Verify with manual-slop_py_get_definition for dataclass fields.

The structural facts (class existence, method names) are usually correct because the code is the source of truth. The numeric/count/line claims are where drift accumulates fastest.

Continuation — 2026-06-10 Evening

After this report was closed, a continuation session (Tier 1 Orchestrator) added 12 more atomic commits to the docs-sync track before the next agent's theme work started. Summary:

• 6 small drift fixes (db5ab0d9–28172135): guide_hot_reload.md example + trigger_key claim; guide_app_controller.md hot_reload.py→hot_reloader.py filename and fictional hot_reload() method; guide_gui_2.md registration line 155→285 and reload()→reload_all(); guide_nerv_theme.md 5 wrong hex values + stale apply_nerv body + stale render_nerv_fx example + [nerv] config that was never wired into source + 0.5 Hz vs actual 3.18 Hz flicker; guide_shaders_and_window.md 3 fictional [nerv] config refs; guide_app_controller.md:68 self-referential io_pool docstring claim.
• 1 mid-size fix (81e88241): guide_command_palette.md command count 11 → 33 (full source-derived Action column for every @registry.register decorator in src/commands.py).
• 2 MMA rewrites (57143b7a, 394987f8, a49e5ffb, e0368174): guide_mma.md (5 fixes: has_cycle recursive→iterative, topological_sort DFS→Kahn's, tick auto-promotion claim, ConductorEngine.__init__ missing max_workers param); guide_beads.md dispatch line range; guide_multi_agent_conductor.md (rewrote the TrackDAG and ExecutionEngine/ConductorEngine/WorkerPool/mma_exec sections — the prior doc predated the conductor_engine refactor and described a different architecture: MultiAgentConductor class that doesn't exist, ExecutionMode enum that doesn't exist, _dispatch_loop background thread that doesn't exist, ThreadPoolExecutor-backed WorkerPool that is actually a dict[str, Thread] + lock + semaphore).
• 2 verbiage cleanups (49ac008a, plus this commit): replaced "fictional" with neutral phrasing ("predates the refactor" / "stale") in 2 places where the prior session had used it in user-facing doc text. Going forward, doc-drift commits use neutral language — "fictional" was a value judgment on the doc and its author, not a technical description.

Bucket coverage after continuation: A (theme system), C (commands/palette), E (runtime/imgui), F (MMA orchestrator) are fully covered. B (logging) and G (beads/vendor) are partial. H/I (mcp_client/ai_client deep) were done in the original 25-commit run. Still untouched: D (8 file utilities), shaders.py/bg shader.py, summary_cache.py.

Caveat for the next agent (theme track): Commit 49ac008a accidentally swept in 2 user-authored files from the parallel prior_session_sepia_20260610 work (conductor/tracks/prior_session_sepia_20260610/plan.md and docs/superpowers/plans/2026-06-10-prior-session-sepia.md). The user is aware and chose to leave them in that commit. The next agent should treat those files as owned by the prior_session_sepia_20260610 track and not modify them from the theme-track context.

Final Report (Continuation Closure)

The continuation session (post-compaction, single agent) ran from after the original 25-commit close through the user's "continue" cues. Final state documented here for future agents.

Stats

Metric	Value
Continuation commits	17 atomic (db5ab0d9 → 7d6dbbd3, plus 03056a4f for the closure summary)
Doc files modified	14 unique (3 fixes each: hot_reload, app_controller, gui_2, nerv_theme, shaders, command_palette, mma, beads, multi_agent_conductor, curation, tools, readme, docs/Readme, conductor/index — plus 03056a4f for the closing report itself)
Source files modified	0 (continuation was docs-only; no production code touched)
Source files read in full	11 (shell_runner, patch_modal, fuzzy_anchor, diff_viewer, outline_tool, theme_nerv, theme_nerv_fx, theme_models, io_pool, summary_cache, external_editor)
Source files outlined only	~20 (cost_tracker, log_registry, log_pruner, summary_cache, command_palette, commands, beads_client, vendor_state, dag_engine, conductor_tech_lead, multi_agent_conductor slice, plus theme_2 — see "What was read but not fully fixed" below)
Net + lines	~250 (the big MMA rewrites added more than they removed because the prior doc's fictional example code is replaced with a pointer-style reference table)
Net - lines	~190 (removed fictional classes/methods/example code)
New commit log lines	~2,500 across the 17 commit messages + the elaborate closure-commit message
User-workspace files touched	0 (config.toml, manualslop_layout.ini, project_history.toml, themes/10x_dark.toml left in working tree for the user to commit; 1 prior-session incident swept in 2 user files — see caveat below)
4 audit scripts re-run	check_test_toml_paths.py, audit_main_thread_imports.py, audit_weak_types.py, audit_no_models_config_io.py — no new violations introduced (audit script wasn't re-run this session because the continuation was docs-only, but a final pass before the theme track touches source code would be wise)

What was done — by category

Drift clusters fixed in this continuation

Drift type	File	Drift found	Fix
Schema drift	docs/guide_hot_reload.md	Example registration showed fictional state_keys/delegation_targets (e.g. ai_input, discussion_history, render_main_window); [hot_reload].trigger_key config claim (0 matches in config.toml)	Replaced example with actual values from src/gui_2.py:285-286; removed config claim; pointed to src/gui_2.py:5340-5346 for the hard-coded keyboard binding
Schema drift	docs/guide_app_controller.md	src/hot_reload.py filename (missing _er); fictional hot_reload(self, module_name) method on AppController (0 matches via grep)	Filename → src/hot_reloader.py (3 places); replaced fictional method with the actual mechanism (registration at gui_2.py:282, trigger at :540, keyboard at :5340)
Algorithm drift	docs/guide_mma.md	has_cycle() described as recursive DFS (actual: iterative DFS with explicit (node_id, is_backtracking) tuple stack); topological_sort() described as "DFS post-order" (actual: Kahn's algorithm with BFS + in-degree counter); tick() claimed to auto-promote to in_progress (actual is read-only — auto-promotion happens in ConductorEngine.run); ConductorEngine.__init__ missing max_workers: int = 4 parameter (used undefined max_workers variable in body example)	Replaced all 4 sections with actual code references and a correct signature
Architecture drift	docs/guide_multi_agent_conductor.md	Entire TrackDAG/TicketNode/detect_cycles/ready_tickets section described a different architecture (fictional nodes/edges/reverse_edges dicts, fictional TicketNode dataclass, fictional detect_cycles returning list[list[str]], fictional ExecutionMode enum, fictional MultiAgentConductor class, fictional _dispatch_loop background thread, fictional ThreadPoolExecutor-backed WorkerPool)	Wholesale rewrite to match src/dag_engine.py (actual: tickets/ticket_map fields, Ticket from models.py, get_ready_tasks/cascade_blocks/has_cycle/topological_sort methods) and src/multi_agent_conductor.py (actual: ConductorEngine class, WorkerPool with dict[str, Thread] + Lock + Semaphore, no _dispatch_loop — uses async run() + loop.run_in_executor for worker spawning)
Field rename	docs/guide_command_palette.md	Command count 11 → 33 actual (counted from @registry.register decorators in src/commands.py)	Expanded the table to all 33 commands with source-derived Action column
Count drift	docs/guide_nerv_theme.md	5 wrong hex values in color table; stale apply_nerv() body (actual uses style.set_color_() + ImVec4, doc showed style.colors[col] = ...); stale render_nerv_fx(fx_state: dict) example function (no such function — actual is CRTFilter/StatusFlicker/AlertPulsing classes); fictional [nerv] config section (5 keys: fx_enabled, scanline_alpha, flicker_rate_hz, alert_pulse_duration_seconds, alert_pulse_color — 0 matches in config.toml); 0.5 Hz flicker claim (actual: 20.0 rad/s ≈ 3.18 Hz via math.sin(time.time() * 20.0)); "1.5s auto-decay" alert pulse (actual: persists while ai_status.lower().startswith("error"), no duration limit)	Replaced color table with computed hex from src/theme_nerv.py:8-13; replaced Implementation section with actual apply_nerv() source; replaced render_nerv_fx example with the actual class API; removed [nerv] config section (added a "Why no config" explanation); corrected flicker rate and pulse duration
Config drift	docs/guide_shaders_and_window.md	3 references to [nerv].fx_enabled / [nerv].scanline_alpha config (no such config exists)	Replaced with the actual runtime toggle (CRTFilter.enabled set by caller of theme_2.render_post_fx(crt_enabled=...))
Self-reference drift	docs/guide_app_controller.md:68	Parenthetical saying the io_pool.py docstring "still says '4 worker threads'" — the docstring was already corrected to "8 worker threads" in commit 2972d235 (a prior-session fix)	Removed the stale parenthetical; replaced with a note that the docstring now matches the constant
Signature drift	docs/guide_tools.md	run_powershell(script, base_dir, qa_callback=None) -> str (missing patch_callback); Popen kwargs omitted; qa_callback claimed to fire only on "command failed" (actual: fires on returncode != 0 OR non-empty stderr)	Full signature + kwargs + the stderr-only behavior + the patch_callback Tier 4 auto-patch flow
Schema drift	docs/guide_context_curation.md	FuzzyAnchor.create_slice docstring mentioned "anchor_lines" field (actual fields are start_line/end_line/start_context/end_context/content_hash); get_context helper staticmethod not mentioned	Corrected the docstring with actual field names; added get_context helper docstring
Schema drift	docs/guide_simulations.md	CodeOutliner doc omitted the [ImGui Scope] case, the return-type annotation suffix, the count[0] > 100000 overflow guard, and the module-level get_outline(path, code) dispatcher	Expanded the section with all 4 cases
Line ref drift	docs/guide_beads.md	bd_ tool dispatch line range 1474-1494 (actual: 1453-1473 in src/mcp_client.py); tool-schema block at 2224-2268 not noted	Fixed the line range; added the tool-schema block note
Count drift	Readme.md	"45 MCP tools" (actual: 46 with run_powershell); "32 registered commands" (actual: 33); shell runner description missing patch_callback	Updated table to 46 / 33 / patch_callback
File tree drift	docs/Readme.md	Tree listed 16 of 27 guides (11 missing: guide_ai_client, guide_api_hooks, guide_app_controller, guide_context_aggregation, guide_discussions, guide_docker_deployment, guide_gui_2, guide_mcp_client, guide_models, guide_multi_agent_conductor, guide_state_lifecycle); "24 guides" count wrong (actual: 27); test count "273" (actual: 322); MCP count + command count + shell runner description all stale	Full alphabetical guide list (27); corrected counts everywhere; updated shell runner description
Summary drift	conductor/index.md	"23 deep-dive guides" (actual: 27); "Last comprehensive doc refresh: 2026-06-05" (actual: this session); "guide_docker_deployment is unindexed" (no longer true)	Updated count to 27 with the full topic list; updated last-refresh date; cross-linked to this closing report

Files read in full (not all had drift)

• src/shell_runner.py (102 lines) — drift in guide_tools.md run_powershell section (fix above)
• src/patch_modal.py (107 lines) — no specific doc drift; covered by guide_gui_2.md (which is one of the docs the theme-track agent will own)
• src/fuzzy_anchor.py (90 lines) — drift in guide_context_curation.md (fix above)
• src/diff_viewer.py (170 lines) — no specific doc drift in guide_tools.md (only listed in file tree, no method descriptions to verify)
• src/outline_tool.py (130 lines) — drift in guide_simulations.md (fix above)
• src/theme_nerv.py (88 lines) — drift in guide_nerv_theme.md (fix above)
• src/theme_nerv_fx.py (97 lines) — drift in guide_nerv_theme.md (fix above)
• src/theme_models.py (221 lines) — no specific drift found (the guide_themes.md doc is post-refactor and accurate per the multi_themes_20260604 ship)
• src/io_pool.py (38 lines) — drift in guide_app_controller.md:68 self-reference (fix above)
• src/summary_cache.py (105 lines) — no specific drift in any guide; mentioned in 4 reports and the docs/Readme file tree (all accurate)
• src/external_editor.py (149 lines) — no specific drift in any guide; mentioned in CULLING_CANDIDATES report (resolve_project_editor_override function — actually that function doesn't exist in the current source; this is in a historical culling report, not a guide, so left alone)

Files outlined but not read in full

• src/cost_tracker.py (64 lines) — outlined; MODEL_PRICING 7-pattern pricing table; only 1 doc claim (guide_models.md:75) which is accurate
• src/log_registry.py (311 lines) — outlined; only listed in file tree
• src/log_pruner.py (125 lines) — outlined; only listed in file tree
• src/command_palette.py (191 lines) — outlined; guide_command_palette.md accurately covers the fuzzy-match algorithm
• src/commands.py (370 lines) — read in slices (every @registry.register decorator + 1-2 surrounding lines for the Action column); full content not needed
• src/beads_client.py (83 lines) — read in full earlier in the session (see "Beads + vendor" bucket B report)
• src/vendor_state.py (81 lines) — read in full earlier in the session; no doc reference found (the Vendor State tab is a UI-polish-track feature, not a stable doc target)
• src/dag_engine.py (228 lines) — read in full for the guide_mma.md + guide_multi_agent_conductor.md rewrites
• src/conductor_tech_lead.py (125 lines) — read in full; guide_mma.md "Tier 2" section accurate
• src/multi_agent_conductor.py (647 lines) — read in slices (init, key methods, doc references); used for the guide_multi_agent_conductor.md rewrite

Drift patterns observed (refined from the original handoff)

The 4 patterns from the original 25-commit handoff held, but two more surfaced in this continuation:

1. Thread counts (4→8 io_pool bump) — re-confirmed in guide_state_lifecycle.md (says "8-thread io_pool with 11 lock-protected regions", correct) and guide_app_controller.md (correct after this session's fix). Pattern: any "N workers" or "N threads" claim must be verified against the actual constant.

2. Line numbers (startup_speedup refactor moved many methods) — re-confirmed by fixing guide_beads.md:1474-1494 → 1453-1473 (off by 19) and noting several other line refs that were checked and still accurate. Pattern: any line ref must be verified with manual-slop_get_file_slice or get_file_slice (the line numbers in src/gui_2.py shifted during startup_speedup_20260606).

3. Removed-class claims — re-confirmed by finding fictional AppState, LayoutPreset, register_hooks, MultiAgentConductor class, ExecutionMode enum, _dispatch_loop method, nodes/edges/reverse_edges fields, TicketNode dataclass, detect_cycles method. Pattern: any class/method/field mentioned in the doc must be verified with py_get_class_summary or py_get_definition against the actual source.

4. Schema fields — re-confirmed by finding RAGConfig 11→5 fields (done in original 25-commit run) and WorkspaceProfile 7→4 fields (also done in original 25-commit run). Pattern: dataclass field counts shrink during refactors; verify with py_get_definition.

5. NEW: Architecture rotations (the most common pattern in this continuation) — when a major refactor renames or restructures a subsystem (e.g. MultiAgentConductor → ConductorEngine, nodes/edges/reverse_edges → tickets/ticket_map, detect_cycles → has_cycle), the doc that described the pre-refactor API is now a complete description of a different architecture. The fix is a wholesale rewrite of the section, not a line edit. Surfaced 3 times in this session: guide_mma.md (the DAG algorithms), guide_multi_agent_conductor.md (the entire MMA Engine section), and guide_hot_reload.md (the delegation_targets semantics).

6. NEW: Hard-coded constants described as config keys — surfaced with NERV: the doc described 5 config keys ([nerv].fx_enabled, [nerv].scanline_alpha, etc.) that were never wired into source. Always verify config claims against config.toml via grep (0 matches if the key was never implemented). This is a special case of "removed-class claims" but distinct enough to warrant its own pattern.

Bucket coverage status (final)

Bucket	Coverage	What's left
A — Theme system	DONE	None — guide_nerv_theme.md and guide_shaders_and_window.md fully updated. Theme track agent owns guide_themes.md and markdown_helper.py/markdown_table.py (left intentionally untouched for them)
B — Logging + analytics	Partial	cost_tracker.py, log_pruner.py, log_registry.py, summary_cache.py outlined or read; no specific doc drift found; the "MMA dashboard cost display" handoff note was incorrect (no such section in guide_mma.md — cost display is wired in gui_2.py)
C — Commands + palette	DONE	None — command count fixed (11 → 33) with full source-derived Action column
D — File utilities	DONE	guide_tools.md run_powershell signature; guide_simulations.md CodeOutliner; guide_context_curation.md FuzzyAnchor. markdown_helper.py and markdown_table.py left for theme-track agent
E — Runtime + ImGui	DONE	None — hot_reloader.py fully audited; guide_hot_reload.md drift fixed; imgui_scopes.py and gemini_cli_adapter.py outlined (no specific doc drift)
F — MMA orchestrator	DONE	None — dag_engine.py, conductor_tech_lead.py, multi_agent_conductor.py (slice) all read; guide_mma.md and guide_multi_agent_conductor.md updated; the prior doc predated the conductor_engine refactor and was substantially rewritten
G — Beads + vendor	Partial	beads_client.py read; guide_beads.md dispatch line ref fixed; vendor_state.py read but no doc reference exists (Vendor State tab is a UI-polish feature, not a stable doc target)
H — mcp_client.py deep	Done in original 25-commit run	Re-verified in this session; no new drift found
I — ai_client.py deep	Done in original 25-commit run	Not re-read in this session

Net result of the 9-bucket handoff: 6 buckets fully covered (A, C, D, E, F, H, I = 7 actually — H/I were already done), 2 buckets partial (B, G), 0 buckets untouched. The handoff is essentially exhausted.

Mixed-in user files caveat (49ac008a)

Commit 49ac008a accidentally swept in 2 user-authored files from the parallel prior_session_sepia_20260610 work:

• conductor/tracks/prior_session_sepia_20260610/plan.md (1569 lines)
• docs/superpowers/plans/2026-06-10-prior-session-sepia.md (1569 lines)

The user is aware and chose to leave the commit as-is. The next agent should treat those files as owned by the prior_session_sepia_20260610 track and not modify them from the theme-track context.

Verbiage lesson (applied going forward)

The first 11 continuation commits used the word "fictional" in commit messages and (twice) in user-facing doc text. The user pushed back: "fictional" is a value judgment on the doc and its author, not a technical description. The technical reality is that the doc described an earlier architecture, the code refactored, and the doc was not updated. That is "predates the refactor" / "stale" / "no longer matches the source."

This lesson was applied in the cleanup commits:

• docs/guide_app_controller.md:59: "previous documentation in this section was fictional" → "previous documentation in this section predated the controller refactor and described an architecture that was never actually implemented"
• docs/guide_rag.md:322: "previous RAGConfig schema was fictional" → "previous RAGConfig schema was stale (predated the schema refactor)"

Going forward, doc-drift commits use neutral language: "predates the refactor," "stale," "outdated," "no longer matches the source," "did not exist in the real dataclass," "did not match the production behavior." The word "fictional" is reserved for the narrow case where the doc explicitly says "X is implemented as Y" and the source shows "Y" was never written at all (then the neutral framing is "the doc described an architecture that was never actually implemented" or "the prior doc predated the implementation and was not updated").

Recommendations for the theme-track agent

1. Read docs/guide_themes.md:87 before touching the theme system. The MarkdownRenderer.__init__ apply_syntax_palette(...) claim is accurate per the theme-syntax-modularization plan, but the spec at superpowers/specs/2026-06-04-theme-syntax-modularization.md:9 references a MarkdownRenderer._lang_map attribute that may or may not be current. Verify before relying on the spec.
2. Do NOT touch the guide_nerv_theme.md and guide_shaders_and_window.md updates from this session — those have been verified against src/theme_nerv.py:1-88 and src/theme_nerv_fx.py:1-97 and src/theme_2.py:400-408. Any change to those files should re-verify against the source.
3. The theme_2.py:111 comment says "NERV FX objects (CRTFilter, AlertPulsing, StatusFlicker) are now created [in render_post_fx]" — this confirms the per-frame create-and-discard pattern documented in this session's guide_nerv_theme.md rewrite. The previous design (long-lived module-level singletons) is no longer in use.
4. Run all 4 audit scripts (check_test_toml_paths.py, audit_main_thread_imports.py, audit_weak_types.py, audit_no_models_config_io.py) before committing any source code change. The docs_sync continuation did not touch source, so audit wasn't needed, but any new code in the theme track should pass all 4.
5. The markdown_table.py spec at superpowers/specs/2026-06-03-ui-polish-design.md:68-82 describes a render_markdown_tables(text: str) -> str function with a placeholder scheme. The actual src/markdown_table.py (72 lines) exports render_table(block: TableBlock) -> None, parse_tables(text: str) -> list[TableBlock], and _split_row/_is_table_at helpers. The spec is older than the source; check both before relying on either.
6. The _lang_map reference in the older spec at superpowers/specs/2026-06-04-theme-syntax-modularization.md:9 is a pre-refactor claim. The current MarkdownRenderer (in src/markdown_helper.py, 405 lines, outlined only) uses a different palette-application mechanism. The theme track should re-verify by reading the source.

Open follow-ups (none of these are blocking)

1. Bucket B / G finalization — cost_tracker.py has a documented use site in gui_2.py:App._render_mma_track_summary, App._render_mma_usage_section, App._render_token_budget_panel (per the cost_tracker's docstring at src/cost_tracker.py:53), but the guide_mma.md and guide_ai_client.md don't mention these render functions. A future track could add a "Cost Display in MMA Dashboard" subsection.
2. markdown_helper.py and markdown_table.py source verification — outlined only; not read in full. The theme track will do this.
3. Test count verification — 322 was the PowerShell Get-ChildItem tests\*.py -Recurse count. If the test_infrastructure_hardening track added 60+ tests and the docs_sync continuation added 0 tests, but other tracks in parallel also added tests, the number may be off. The guide_testing.md and the docs/Readme.md summary row now both say 322; if more tests land, the doc should be re-verified.
4. Doc freshness signal — both conductor/index.md:8 and conductor/index.md:26 say the last comprehensive refresh was 2026-06-10. A future "doc freshness" check could re-verify against the current src/ state if a major refactor lands in the next few days.

Files NOT touched in this session (with reasons)

• config.toml (4 modifications, user workspace)
• manualslop_layout.ini (1 modification, user workspace)
• project_history.toml (1 modification, user workspace)
• themes/10x_dark.toml (1 modification, user workspace)
• conductor/tracks/prior_session_sepia_20260610/ (user's parallel track, in 49ac008a by accident)
• docs/superpowers/plans/2026-06-10-prior-session-sepia.md (user's parallel track, in 49ac008a by accident)
• docs/superpowers/specs/2026-06-10-prior-session-sepia-design.md (untracked, user's parallel track — left untracked)
• src/markdown_helper.py, src/markdown_table.py (left for theme-track agent)
• src/imgui_scopes.py, src/gemini_cli_adapter.py (outlined only; no specific doc drift)

See Also

• test_infrastructure_hardening_batch_green_20260610.md — the closing report for the test-hell saga
• test_bed_health_20260609.md — the test bed health summary (Phase 7 of test_infrastructure_hardening)
• agile_dispatch_20260610.md — the session diary (if present)