From f1f0e553f8568e048262d358326d0f929b144c35 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Wed, 10 Jun 2026 22:32:22 -0400 Subject: [PATCH] docs(report): append handoff section to docs_sync closing report Adds a 'Handoff: Remaining Drifted Docs' section listing: - 4 already-fixed stale refs found proactively outside the original 4-commits scope (Readme, 2 reports, guide_tools, 2 source docstrings) - 9 categories of remaining work (A through I) with file lists, LOC, and which docs reference each bucket - A recommended 3-track decomposition that fits each category in one agent context frame - The 4 most-common drift patterns I encountered (thread counts, line numbers, removed-class claims, schema fields) The next agent can pick up directly from this section without re-doing the audit I already completed. --- docs/reports/docs_sync_test_era_20260610.md | 84 +++++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/docs/reports/docs_sync_test_era_20260610.md b/docs/reports/docs_sync_test_era_20260610.md index 5c507dac..e3d848ef 100644 --- a/docs/reports/docs_sync_test_era_20260610.md +++ b/docs/reports/docs_sync_test_era_20260610.md @@ -128,6 +128,90 @@ When the next agent engages `qwen_llama_grok_integration_20260606`: 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_.log` but actual is `logs/sessions//comms.log` (the `` 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. + ## See Also - [test_infrastructure_hardening_batch_green_20260610.md](test_infrastructure_hardening_batch_green_20260610.md) — the closing report for the test-hell saga