From e5a8a84381c0dc5efc8831ad820e260c84bc2f00 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Thu, 2 Jul 2026 19:02:35 -0400 Subject: [PATCH] docs(conductor): type_aliases count, tracks.md stale rows, index.md guide count - product-guidelines.md: '10 aliases' -> core + extended per-aggregate dataclasses (Metadata, CommsLogEntry, ... PathInfo, FileItemsDiff, JsonPrimitive/JsonValue) reflecting the actual ~19 types in src/type_aliases.py. - tracks.md: marked rows 2 (qwen_llama_grok), 3 (data_oriented_error handling), 17 (code_path_audit) as Completed per chronology.md (they were stale 'in progress' / 'ready to start'). Added cleanup note. data_structure_strengthening already dropped. - index.md: '27 deep-dive guides' -> 41 (actual count in docs/); refreshed last doc-refresh date to 2026-07-02 with the drift-fix summary. --- conductor/index.md | 4 ++-- conductor/product-guidelines.md | 7 +++++-- conductor/tracks.md | 8 +++++--- 3 files changed, 12 insertions(+), 7 deletions(-) diff --git a/conductor/index.md b/conductor/index.md index 87a4fc22..da6c79d2 100644 --- a/conductor/index.md +++ b/conductor/index.md @@ -5,7 +5,7 @@ - [Product Definition](./product.md) — Vision, primary use cases, and key features - [Product Guidelines](./product-guidelines.md) — Code style, process, and architectural patterns - [Tech Stack](./tech-stack.md) — Python 3.11+, ImGui Bundle, FastAPI, all SDKs and modules -- [Human-Facing Documentation](../docs/Readme.md) — **27 deep-dive guides** (architecture, MMA, tools, simulations, testing, per-source-file references, RAG, Beads, hot reload, personas, NERV theme, workspace profiles, command palette, themes, context curation, AI client, MCP client, app controller, GUI main, models, multi-agent conductor, state lifecycle, discussions, context aggregation, docker deployment, and more) +- [Human-Facing Documentation](../docs/Readme.md) — **41 deep-dive guides** (architecture, MMA, tools, simulations, testing, per-source-file references, RAG, Beads, hot reload, personas, NERV theme, workspace profiles, command palette, themes, context curation, AI client, MCP client, app controller, GUI main, models, multi-agent conductor, state lifecycle, discussions, context aggregation, docker deployment, and more) ## Workflow @@ -23,4 +23,4 @@ - [Recently Shipped: Multi-Theme TOML System](./tracks/multi_themes_20260604/) — 8 new theme files, public API (`load_themes_from_disk`, `get_syntax_palette_for_theme`, `apply_syntax_palette`), color-callable convention. See [../docs/guide_themes.md](../docs/guide_themes.md) for the authoring guide. - [Recently Shipped: Test Regression Fixes (post multi-themes ship)](./tracks/regression_fixes_20260605/) — 11 of 21 failing tests fixed, root cause of remaining live_gui C-level crash identified (`_ini_capture_ready` defer-not-catch pattern). -Last comprehensive doc refresh: 2026-06-10 (27 guide_*.md files, all now indexed in [docs/Readme.md](../docs/Readme.md)). 8 new guides added in the 2026-06-02 docs layer refresh: testing + 7 per-source-file references. Latest addition: `guide_themes.md` (2026-06-04, multi_themes_20260604 ship). The docs_sync_test_era_20260610 track (closed 2026-06-10) verified all 27 guides against the current `src/` source; see [docs/reports/docs_sync_test_era_20260610.md](../docs/reports/docs_sync_test_era_20260610.md) for the closing report. See [docs/Readme.md](../docs/Readme.md) for the full index. +Last comprehensive doc refresh: 2026-07-02 (41 guide_*.md files in `docs/`, all indexed in [docs/Readme.md](../docs/Readme.md)). Earlier refreshes: 2026-06-10 (27 guides verified against src/), 2026-06-02 (8 per-source-file guides added). Latest drift-fix pass: 2026-07-02 (guide_models.md rewritten for src/models.py shim reality; provider count + file sizes + mcp_tool_specs split corrected in product.md + tech-stack.md; send_result claim corrected in product-guidelines.md; audit_optional_returns.py phantom-script reference fixed in python.md). See [docs/Readme.md](../docs/Readme.md) for the full index. diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md index 57ea4e73..5244da82 100644 --- a/conductor/product-guidelines.md +++ b/conductor/product-guidelines.md @@ -98,9 +98,12 @@ section for the full taxonomy. The codebase follows the "names for shapes" pattern: every `dict[str, Any]` or `list[dict[...]]` should use a `TypeAlias` from `src/type_aliases.py`. -The 10 aliases (`Metadata`, `CommsLogEntry`, `CommsLog`, `HistoryMessage`, +The core aliases (`Metadata`, `CommsLogEntry`, `CommsLog`, `HistoryMessage`, `History`, `FileItem`, `FileItems`, `ToolDefinition`, `ToolCall`, -`CommsLogCallback`) cover the 86% of common patterns. The canonical +`CommsLogCallback`) plus the extended per-aggregate dataclasses +(`SessionInsights`, `DiscussionSettings`, `CustomSlice`, `MMAUsageStats`, +`ProviderPayload`, `UIPanelConfig`, `PathInfo`, `FileItemsDiff`, plus +the `JsonPrimitive`/`JsonValue` pair) cover the common patterns. The canonical reference is in [`conductor/code_styleguides/type_aliases.md`](code_styleguides/type_aliases.md). diff --git a/conductor/tracks.md b/conductor/tracks.md index 081baebd..22b0f081 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -18,11 +18,11 @@ Tracks that are unblocked and ready to start. Ordered by **dependency** (blocked | # | Priority | Track | Status | Blocked By | |---|---|---|---|---| | 36 | A (sunset) | [MMA Quarantine + RAG Test Decoupling](#track-mma-quarantine--rag-test-decoupling) | spec ✓, plan pending | (none) | -| 2 | A | [Qwen, Llama & Grok Vendor Integration](#track-qwen-llama-grok-vendor-integration) | Phase 6 in progress (docs); NOT archiving — has follow-up | test_infrastructure_hardening_20260609 (merged) | -| 3 | A | [Data-Oriented Error Handling (Fleury Pattern)](#track-data-oriented-error-handling) | spec ✓, plan ✓, ready to start | test_infrastructure_hardening_20260609 (merged), qwen_llama_grok | +| 2 | A | [Qwen, Llama & Grok Vendor Integration](#track-qwen-llama-grok-vendor-integration) | **Completed** (per chronology.md; Phase 6 follow-up shipped) — row retained for cross-ref; archive candidate | test_infrastructure_hardening_20260609 (merged) | +| 3 | A | [Data-Oriented Error Handling (Fleury Pattern)](#track-data-oriented-error-handling) | **Completed** (per chronology.md) — archive candidate | test_infrastructure_hardening_20260609 (merged), qwen_llama_grok | | 4 | A | [MCP Architecture Refactor (Sub-MCP Extraction)](#track-mcp-architecture-refactor) | spec ✓, plan pending | test_infrastructure_hardening_20260609 (merged), data_oriented_error_handling, data_structure_strengthening | | 16 | A | [Test Sandbox Hardening](#track-test-sandbox-hardening) | spec ✓, plan ✓, ready to start | (none) | -| 17 | A | [Code Path Audit](#track-code-path-audit) | spec ✓ + plan ✓ | test_infrastructure_hardening_20260609 (merged), any_type_componentization (shipped), phase2_4_5_call_site_completion (shipped) | +| 17 | A | [Code Path Audit](#track-code-path-audit) | **Completed** (per chronology.md) — archive candidate | test_infrastructure_hardening_20260609 (merged), any_type_componentization (shipped), phase2_4_5_call_site_completion (shipped) | | 22b | A | [Meta-Tooling Workflow Review](#track-meta-tooling-workflow-review) | spec ✓, plan ✓, parked | (none) | | 23 | A | [Intent-Based Scripting Languages Survey](#track-intent-dsl-survey) | spec ✓, plan pending | (none) | | 25 | B | [Fable System Prompt Review](#track-fable-review) | spec ✓, plan pending | (none) | @@ -33,6 +33,8 @@ Tracks that are unblocked and ready to start. Ordered by **dependency** (blocked | 7c | B | [SQLite-Granularity Inline Docs for ai_client.py](#track-sqlite-docs-ai-client) | spec ✓, plan ✓, ready to start | (none) | | 19 | — | [Context First Message Fix](#track-context-first-message-fix) | spec TBD | (none) | +> **Stale-row cleanup (2026-07-02):** rows 2, 3, 17 marked Completed per `conductor/chronology.md` (which is the canonical status source). They are retained here as archive candidates pending a `git mv` to `conductor/archive/`. `data_structure_strengthening_20260606` (also Completed per chronology) was already dropped from this table. + ### Track detail anchors - **MMA Quarantine + RAG Test Decoupling** → `conductor/tracks/mma_quarantine_rag_test_decoupling_20260701/`