docs(refresh): 3 new guides + cross-links from nagent_review

Per the docs Refresh Protocol (conductor/workflow.md), after a reference/analysis track ships, the affected guides must be updated to reflect new module structure or new conventions. The nagent_review track (9cc51ca9) produced a deep-dive + 10 actionable takeaways that named 3 documentation gaps in /docs. This commit fills them. 3 new guides (1,122 lines total): 1. guide_discussions.md (353 lines) — The Discussion system - 23-operation matrix: A1-A7 per-entry + B1-B11 discussion-level + C1-C5 undo/redo - Take naming convention (<base>_take_<n>), branching, promotion - User-managed role list (app.disc_roles) - Per-role filter linked to MMA persona focus - _disc_entries_lock thread-safety contract - Hook API session endpoints - Persistence: _flush_to_project, _flush_disc_entries_to_project, context_snapshot - 9 file:line refs into gui_2.py:3770-4260 + history.py 2. guide_state_lifecycle.md (375 lines) — Undo/redo + reset + state delegation - HistoryManager + UISnapshot (13 captured fields, 100-snapshot capacity, debounced change-detection at render frame) - _handle_reset_session (clears 30+ fields, replaces project, preserves active_project_path per the 2026-06-08 regression fix) - App.__getattr__/__setattr__ state delegation to Controller - 4-thread access pattern with 7 lock-protected regions - State persistence: in-memory vs project TOML vs config TOML - Hot-reload integration - Hook API registries (_predefined_callbacks, _gettable_fields) - 14 file:line refs into gui_2.py:1140-1170, history.py, app_controller.py:3286-3356 3. guide_context_aggregation.md (394 lines) — The aggregate.py pipeline - 3 aggregation strategies (auto, summarize, full) - 7 per-file view modes (full, summary, skeleton, outline, masked, custom, none) - Full FileItem schema (9 fields + __post_init__ normalizer) at models.py:510-559 - ContextPreset schema and ContextPresetManager - Tier 3 worker variant (build_tier3_context with FuzzyAnchor re-resolution and focus-file handling) - force_full / auto_aggregate short-circuits - Cache strategy (static prefix + dynamic history) - 23 file:line refs into aggregate.py:36-518 + models.py:909-937 8 existing guides cross-linked to the 3 new guides and to the nagent_review track: - guide_gui_2.md (+ See Also entries for discussions, state lifecycle, context aggregation, nagent_review report) - guide_app_controller.md (+ See Also entries for discussions, state lifecycle, context aggregation, nagent_review report) - guide_context_curation.md (+ new See Also section pointing to context aggregation + nagent_review) - guide_architecture.md (+ new See Also section listing all 10 guides + nagent_review report) - guide_ai_client.md (+ See Also entries for state lifecycle, context aggregation, nagent_review pitfalls #2 and #4) - guide_mma.md (+ new See Also section pointing to context aggregation, discussions, nagent_review report §9 + takeaways §3/§10 for SubConversationRunner priority) - guide_models.md (+ See Also entries for context aggregation, discussions, nagent_review report §6 on FileItem as strongest curation dimension) - Readme.md (+ 3 new guide entries in the index table, with one-line summaries) No code modified. This is documentation only. Why these 3 guides specifically: - guide_discussions.md: The discussion system is the user's most edited surface. nagent_review's report §3 enumerated 23 operations (A1-C5) that previously existed only as scattered file:line refs across gui_2.py. A dedicated guide makes the operation matrix discoverable. - guide_state_lifecycle.md: The undo/redo + reset + state delegation machinery is architecturally load-bearing but scattered across 4 files. After nagent_review identified the provider-side history divergence as Pitfall #4, the relationship between Manual Slop's state and the provider's state needs explicit documentation. - guide_context_aggregation.md: aggregate.py (518 lines) is the most-touched module after ai_client.py but had no dedicated guide. nagent_review confirmed it's Manual Slop's strongest curation dimension. A dedicated guide makes the 7 view modes and 3 strategies discoverable. The 3 new guides total 1,122 lines and follow the existing per-source-file deep-dive style (architectural, data-oriented, state-management-focused).
2026-06-08 19:26:08 -04:00
parent 9cc51ca9af
commit ba05168493
11 changed files with 1180 additions and 4 deletions
@@ -562,3 +562,15 @@ The `WorkspaceManager` (`src/workspace_manager.py`) supports binding workspace p
 - This is opt-in via `[conductor].auto_switch_profiles = true` in `config.toml`.

 See [guide_workspace_profiles.md](guide_workspace_profiles.md) (placeholder; written in Task 10) for the full profile schema.
+
+---
+
+## See Also
+
+- **[guide_architecture.md](guide_architecture.md)** — Threading model that MMA's worker pool respects
+- **[guide_multi_agent_conductor.md](guide_multi_agent_conductor.md)** — The `multi_agent_conductor.py` + `dag_engine.py` runtime
+- **[guide_app_controller.md](guide_app_controller.md)** — How the AppController drives MMA via `_cb_start_track`, `_do_generate`, `_process_event_queue`
+- **[guide_context_aggregation.md](guide_context_aggregation.md)** — The `aggregate.py:build_tier3_context` variant used by MMA workers
+- **[guide_discussions.md](guide_discussions.md)** — The Discussion system; MMA worker prompts are built from the active discussion
+- **[conductor/tracks/nagent_review_20260608/report.md §9](../../conductor/tracks/nagent_review_20260608/report.md)** — Deep-dive on the MMA sub-conversation pattern vs nagent's `<nagent-conversation>` tag; **the highest-priority future-track is to extract MMA's `run_worker_lifecycle` into a reusable `SubConversationRunner` for 1:1 discussions** (per user-flagged want)
+- **[conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md §3 and §10](../../conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md)** — Actionable patterns for the SubConversationRunner; the design constraint that sub-agents return a *concise artifact* (not a full transcript) is baked into the recommendation