The previous header said 'MCP Tools (46 tools)' which was technically
correct only if counting the full AGENT_TOOL_NAMES list. But this
module actually defines only 45 tools in MCP_TOOL_SPECS. The 46th
is run_powershell, which is handled by src/shell_runner.py.
Updated the header to be honest about the split: 45 MCP tools in
this module + 1 shell tool in shell_runner.py = 46 total. Added
a forward reference to guide_tools.md for run_powershell.
The top-of-file docstring claimed 'logs/sessions/comms_<ts>.log' with
<ts> as a filename prefix. Actual: per-session subdir
'logs/sessions/<session_id>/' with plain filenames (comms.log,
toolcalls.log, apihooks.log, clicalls.log). The <ts>/session_id
is the PARENT DIR, not a filename prefix.
Per commit 73e1a36d (per-session subdirs), the per-session
directory is the unit of isolation. apihooks.log is a fourth
log file the old docstring omitted entirely.
Also added the new files (apihooks.log, outputs/ subdir) and
clarified the scripts/generated/ dual-write pattern.
Per IO_POOL_MAX_WORKERS = 8 (set in commit 4a338486 on 2026-06-06
to relieve contention during batched sims), the pool actually has
8 workers, not 4. The docstring was stale. Also added the SHAs
of the 4->8 bump for traceability.
Re-audit after reading the actual full file contents:
1. guide_app_controller.md (the __init__ walkthrough):
- '4-thread ThreadPoolExecutor' -> '8-thread' per IO_POOL_MAX_WORKERS = 8
in src/io_pool.py:20 (bumped from 4 in commit 4a338486; the io_pool.py
module docstring is also stale and says '4 worker threads' - flagged
for a separate fix).
- '12 locks' -> '11 locks + 5 non-lock state fields' (re-counted the
threading.Lock() and the _rag_sync_*/_project_switch_* fields).
2. guide_app_controller.md (the closing line):
- '12 locks' -> removed; explained the 434-line __init__ body
composition (locks + state fields + settable_fields + gui_task_handlers).
3. guide_rag.md (Future Work section):
- 'The _search_mcp method is a placeholder for this' -> WRONG.
_search_mcp (src/rag_engine.py:322) IS a real implementation that
calls mcp_client.async_dispatch when vector_store.provider == 'mcp'.
Rewrote the future-work item to describe the actual mechanism.
4. docs/reports/docs_sync_test_era_20260610.md (the closing report):
- Same 4-thread->8 and 12-locks->11 corrections propagated.
The structural facts (WorkspaceProfile/RAGConfig/VectorStoreConfig field
lists, method existence, _init_actions/_load_active_project line
numbers, _LiveGuiHandle existence, etc.) were all correct. The
counting/threading-pool claims I cited from memory were the ones
that needed re-verification.
The Phase 6+ section had two duplicate '### Active' headers, which
made the chronology confusing. The user (paraphrased): preserve the
chronology of project progress, don't need full detail, follow the
previous restructure's lightweight pattern.
Changes:
- Add '### Recently Completed (2026-06-06 to 2026-06-10)' subsection
containing the 3 closed tracks (startup_speedup, test_batching_refactor,
test_infrastructure_hardening) with lightweight entries: per-phase
commit SHAs only, 1-line summary, link to spec/plan/state folder.
Trimmed the verbose per-sub-track commentary that was in the old
startup_speedup entry (the per-sub-track bullets for warmup, status
indicator, audit violations, post-shipping fixes are in the
archive's spec/plan, not the tracks.md).
- Remove the duplicate '### Active' header.
- Update section intro to reflect '3 recently completed, 4 in plan'
(was '2 already completed, 3 in plan').
- test_infrastructure_hardening entry now has phase commit SHAs
(5df22fa8, 67d0211e, 006bb114, b8fcd9d6, 33d5cac, 7b87bbf5,
84edb200, 719fe9a) instead of just the closing-report link.
Chronology is now visible at a glance; per-track full detail is
in the linked archive/ folder.
Honest report: when re-verifying the 4 commits the user asked about
(d82153c0, f973fb27, 5aa19e59, 237f5725), I found 3 docs claims I
made WITHOUT actually reading the code:
1. f973fb27 guide_workspace_profiles.md activation step 4:
Claimed 'App._apply_panel_states'. This method does not exist.
Actual: App._apply_workspace_profile(profile) iterates
profile.panel_states.items() and setattr on App. See
src/gui_2.py:844-848.
2. 237f5725 guide_app_controller.md Manager objects paragraph:
Claimed 'App._post_init at src/gui_2.py:3995'. Actual line: 492
(off by ~3500 lines; the file was refactored during
startup_speedup and many earlier-line methods were deleted).
3. 237f5725 guide_app_controller.md closing paragraph:
Claimed 'AppController.__init__ at src/app_controller.py:778-836'.
Actual range: 778-1212 (the method body is much longer than I
assumed; the trailing 800-1212 is locks/io_pool/warmup/manager
wiring). Note added to explain the long range.
Fixes the wrong claims with line numbers I re-verified via AST.
The structural claims (data structure fields, line numbers of
_validate_collection_dim, _init_vector_store, _LiveGuiHandle,
etc.) WERE all verified and are correct.
The previous note in guide_rag.md §RAGConfig Schema said:
'ast_chunking_enabled lives in ChunkingConfig (not in RAGConfig)'
This was a documentation lie. Verified by grep:
- 'class ChunkingConfig' returns 0 matches in src/
- 'ast_chunking_enabled' returns 0 matches anywhere in src/
- The 5 fields (ast_chunking_enabled, auto_index_on_load,
auto_sync_interval_seconds, vector_store_backend, vector_store_path)
were never in the real RAGConfig. They were fictional.
Rewrite the note to be honest: 'the old doc was fictional; the
real RAGConfig has 5 fields; the other 5 fields never existed'.
Clarify that top_k is a real runtime parameter (on
RAGEngine.search()) not a config field.
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.
- state.toml: status active->completed, all 25 tasks marked complete
with commit SHAs, all 4 phases checkpointed
- metadata.json: status active->shipped, 17-commit list, all 9
verification criteria flipped to DONE
- Structural Testing Contract (mirrors workflow.md)
- Isolated-Pass Verification Fallacy (Lesson 1, with link to the
test_infrastructure_hardening_batch_green_20260610 incident report
that motivated the rule)
- Audit Scripts as CI Gates (4 scripts: check_test_toml_paths,
audit_main_thread_imports, audit_weak_types, audit_no_models_config_io)
- Skip Markers Are Documentation, Not Avoidance (workflow.md policy)
Known Pitfalls (new subsection):
- HARD BAN: git checkout -- <file>, git restore, git reset
(per AGENTS.md Critical Anti-Patterns; destroyed user in-progress
edits twice on 2026-06-07; concrete 2026-06-10 incident:
mma_tier_usage_reset_fix regression)
Live_gui Test Fragility (2 new subsections):
- Anti-pattern: push_event + time.sleep(N) + assert is a race.
Fix: poll-until-state-visible with bounded retries. 5+ tests
affected in 2026-06-10 batch-green wave.
- Async setters need poll-for-state. mma_state_update and rag_*
setters dispatch to _pending_gui_tasks queue; the setter returns
before the GUI render loop processes the task. Assert immediately
= race. Fix: poll via get_value with bounded retry.
Lesson 5 from the 4-day test-hell saga. The chroma cache lives at
tests/artifacts/.slop_cache/chroma_<collection>/, NOT at the per-run
live_gui_workspace_<timestamp>/ subdir. The trailing-slash bug in
Path(active_project_path).parent places the cache one level higher
than expected.
RAG tests must pre-clean the cache to avoid persistent state from
prior batched runs. Documents the cleanup pattern (shutil.rmtree with
ignore_errors=True), the auto-recovery mechanism (_validate_collection_dim),
and 3 anti-patterns (assuming per-run, not cleaning, asserting on
first chunk in batched context).
New entry at the top of the Recently Shipped list, linking to the
archive/ folder. Includes:
- 314/314 green across all 11 tier batches
- FR1-FR5 summary
- 3 lineage tracks also archived
- The 4 unblocked tracks
- Link to the closing batch-green report
- Remove row 1 from Active Tracks table
- Update rows 2-5, 17: test_infrastructure_hardening_20260609 -> '(merged)'
- Mark test_infrastructure_hardening as [COMPLETE 2026-06-10] [archived]
- Update link to use archive/ instead of tracks/
- Add closing note: 314/314 tests green, lineage tracks also archived
The previous doc showed:
- A fictional AppState dataclass (does not exist)
- A fictional __init__ that creates manager objects in __init__
(managers are lazy via __getattr__, created in _load_active_project)
- A fictional register_hooks(app) method (real flow is _init_actions
called from init_state populates _predefined_callbacks)
- A fictional enable_test_hooks parameter (real signature is
defer_warmup: bool = False, log_to_stderr: Optional[bool] = None;
--enable-test-hooks is parsed by sloppy.py for HookServer, not here)
The new doc describes the real init flow (timeline anchors, 12 locks,
GUI health state, io_pool, warmup manager, flags) and points to the
actual line numbers in src/app_controller.py.
guide_ai_client.md:
- Add 'Module-Level Imports' section explaining that the 5 provider SDKs
are NOT imported at module level; they're obtained via
src.module_loader._require_warmed() after the WarmupManager loads them
in the background. (Per startup_speedup_20260606: import src.ai_client
went from ~1800ms to ~161ms.)
guide_api_hooks.md:
- Add 4 warmup endpoints to the endpoints table:
/api/warmup_status, /api/warmup_wait?timeout=N,
/api/warmup_canaries, /api/startup_timeline
- Add 'Warmup API' section with client methods + external script pattern
(use get_warmup_wait() instead of time.sleep() race)
The live_gui fixture in tests/conftest.py:467 now yields a _LiveGuiHandle
object (not a tuple). The handle exposes:
- .process, .gui_script, .workspace (Path to per-run workspace)
- .is_alive(), .ensure_alive(), .respawn_count
- __iter__ and __getitem__ for backward-compatible tuple unpacking
Also document the xdist O_EXCL file-lock coordination pattern and the
PYTEST_XDIST_WORKER env var owner/client role split.
The 2026-06-05 live_gui_fragility_fixes refactor replaced the old 7-field
WorkspaceProfile (docking_layout: bytes, window_visibility, theme,
theme_fx_enabled, captured_at, description) with a 4-field model:
ini_content: str, show_windows, panel_states. tomli_w rejects bytes,
so the ini_content is now a plain ImGui ini string, not base64.
- Update Data Model class example + field table
- Update Serialization section + TOML example
- Update Profile Activation + Capturing Current State steps
- Update Layout Stability note (binary blob -> raw ini string)
- Replace 'Theme FX State is Global' limitation with 'Theme is Not Captured'
ed