From 8b7b8b96c747567620484e406eba8394958b6040 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Thu, 2 Jul 2026 19:31:32 -0400 Subject: [PATCH] docs(styleguides+harness-plan): fix stale models.py refs + harness plan line drift MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Styleguides: - agent_memory_dimensions.md: FileItem/ContextPreset line refs (src/models.py:510-559 / 909-937) -> src/project_files.py + src/context_presets.py (moved per module_taxonomy_refactor_20260627). - config_state_owner.md: 'file I/O primitives in src/models.py' -> src/project_manager.py (the config-load/save helpers moved). - python.md §10 NOT-exempt list: '12 per-aggregate types' -> ~19; 'dataclass types in src/models.py' -> per-system files enumeration (mma.py, project_files.py, mcp_tool_specs.py, result_types.py, personas.py, workspace_manager.py, mcp_client.py). - type_aliases.md: type-registry lookup examples updated to the per-system files (src_mma.md, src_project_files.md, etc.); the 'src/models.py: 48 dataclass field types' worked-example line is flagged as historical (pre-refactor state). Harness plan (directive_hotswap_harness_20260627/plan.md): - §17 line refs corrected: 17.1 220-237 -> 247-264; 17.2 239-250 -> 266-277; 17.3 252-272 -> 279-299; 17.4 274-299 -> 301-326; 17.5 301-311 -> 328-338; 17.6 313-323 -> 340-350; 17.7 325-327 -> 352-354; 17.9 336-409 -> 364-443. - §17 master range 216-409 -> 243-473. - §12 175-184 -> 202-211; §13 185-199 -> 212-224; §15 205-215 -> 234-241. - error_handling.md: hard rules 212-242 -> 212-264; boundary types 274-311 -> 284-365. - type_aliases.md: 40-81 -> 13-87 + 89-160 + 284-365 (the alias table + decision pattern 2.5 + boundary/anti-pattern sections). --- .../agent_memory_dimensions.md | 5 ++- .../code_styleguides/config_state_owner.md | 4 ++- conductor/code_styleguides/python.md | 4 +-- conductor/code_styleguides/type_aliases.md | 11 +++++-- .../plan.md | 32 +++++++++---------- 5 files changed, 31 insertions(+), 25 deletions(-) diff --git a/conductor/code_styleguides/agent_memory_dimensions.md b/conductor/code_styleguides/agent_memory_dimensions.md index 7a86ec49..3ab4eea5 100644 --- a/conductor/code_styleguides/agent_memory_dimensions.md +++ b/conductor/code_styleguides/agent_memory_dimensions.md @@ -280,9 +280,8 @@ For Manual Slop's current state: | Dim | Where in `src/` | Line range | What to look at | |---|---|---|---| -| Curation | `src/models.py` | 510-559 | `FileItem` schema | -| Curation | `src/models.py` | 909-937 | `ContextPreset` schema | -| Curation | `src/context_presets.py` | (small) | `ContextPresetManager` | +| Curation | `src/project_files.py` | (whole file) | `FileItem` schema (moved out of `src/models.py` per `module_taxonomy_refactor_20260627`) | +| Curation | `src/context_presets.py` | (whole file) | `ContextPreset` schema + `ContextPresetManager` (moved out of `src/models.py`) | | Curation | `src/aggregate.py` | (518 lines) | `build_file_items`, `build_markdown` | | Discussion | `src/gui_2.py` | 3770-3853 | `render_discussion_entry` (A1-A7) | | Discussion | `src/gui_2.py` | 4239-4260 | `render_discussion_entry_controls` (B1-B11) | diff --git a/conductor/code_styleguides/config_state_owner.md b/conductor/code_styleguides/config_state_owner.md index 72fa7b9a..7e2af007 100644 --- a/conductor/code_styleguides/config_state_owner.md +++ b/conductor/code_styleguides/config_state_owner.md @@ -2,7 +2,9 @@ **Rule:** The `AppController` is the single source of truth for the in-memory config (`self.config`) and the only authorized caller of -the file I/O primitives in `src/models.py`. +the file I/O primitives (the config-load/save helpers, which moved out +of `src/models.py` to `src/project_manager.py` per +`module_taxonomy_refactor_20260627`). ## Why diff --git a/conductor/code_styleguides/python.md b/conductor/code_styleguides/python.md index b1821814..d39403d3 100644 --- a/conductor/code_styleguides/python.md +++ b/conductor/code_styleguides/python.md @@ -150,9 +150,9 @@ When refactoring a class to functions: | `HotReloader` + `HotModule` | `src/hot_reloader.py:21,15` | HOT_MODULES registry, last_error, is_error_state | **NOT exempt** (these are dataclasses / data carriers / context managers, not stateful subsystems): -- All `@dataclass(frozen=True)` types in `src/type_aliases.py` (12 per-aggregate types) — pure data +- All `@dataclass(frozen=True)` types in `src/type_aliases.py` (~19 per-aggregate types: Metadata, CommsLogEntry, HistoryMessage, ToolDefinition, SessionInsights, DiscussionSettings, CustomSlice, MMAUsageStats, ProviderPayload, UIPanelConfig, PathInfo, FileItemsDiff, JsonPrimitive, JsonValue, etc.) — pure data - All `@dataclass(frozen=True)` types in `src/openai_schemas.py` (`ToolCall`, `ChatMessage`, `UsageStats`, `NormalizedResponse`, etc.) — pure data -- All `@dataclass` types in `src/models.py` (Ticket, Track, Persona, FileItem, ContextPreset, etc.) — pure data +- All `@dataclass` types in the per-system files (formerly in `src/models.py`, now moved out per `module_taxonomy_refactor_20260627`): `Ticket`/`Track`/`WorkerContext`/`TrackMetadata` in `src/mma.py`, `FileItem` in `src/project_files.py`, `ToolSpec` in `src/mcp_tool_specs.py`, `Result`/`ErrorInfo` in `src/result_types.py`, `Persona` in `src/personas.py`, `WorkspaceProfile` in `src/workspace_manager.py`, `RAGConfig`/`MCPServerConfig` in `src/mcp_client.py` — pure data - All context-manager wrappers in `src/imgui_scopes.py` (`_ScopeChild`, `_ScopeGroup`, etc.) — they wrap scope, not state - `HotModule` is exempt only because it's paired with the `HotReloader` registry class — keep them together diff --git a/conductor/code_styleguides/type_aliases.md b/conductor/code_styleguides/type_aliases.md index c9bde04b..1ed96b27 100644 --- a/conductor/code_styleguides/type_aliases.md +++ b/conductor/code_styleguides/type_aliases.md @@ -250,8 +250,13 @@ uv run python scripts/generate_type_registry.py --diff **When the LLM needs the fields of a type:** ```bash -cat docs/type_registry/src_models.md # for src/models.py types -cat docs/type_registry/type_aliases.md # for the 10 TypeAliases +cat docs/type_registry/src_mma.md # for src/mma.py types (Ticket, Track, WorkerContext, TrackMetadata) +cat docs/type_registry/src_project_files.md # for src/project_files.py (FileItem) +cat docs/type_registry/type_aliases.md # for the per-aggregate dataclasses in src/type_aliases.py +cat docs/type_registry/src_mcp_tool_specs.md # for src/mcp_tool_specs.py (ToolSpec, ToolParameter) +cat docs/type_registry/src_result_types.md # for src/result_types.py (Result, ErrorInfo) +# (the old docs/type_registry/src_models.md reflected the pre-refactor src/models.py; +# models.py is now a ~1.5KB shim — see guide_models.md for the per-system file map) ``` **The "delete to turn off" pattern** (per `feature_flags.md`): `rm -rf docs/type_registry/` disables the registry. Re-enable by running `python scripts/generate_type_registry.py`. @@ -333,7 +338,7 @@ uv run python scripts/generate_type_registry.py **`src/app_controller.py`**: 62 `dict[str, Any]` -> `Metadata`; 20 `list[dict[str, Any]]` -> `list[Metadata]`; 4 `Optional[dict[str, Any]]` -> `Optional[Metadata]`. -**`src/models.py`**: 48 dataclass field types converted to `Optional[Metadata]` / `list[Metadata]`. +**`src/models.py`** (historical — at the time of the `data_structure_strengthening_20260606` track): 48 dataclass field types converted to `Optional[Metadata]` / `list[Metadata]`. **Note:** `src/models.py` has since been reduced to a ~1.5KB re-export shim per `module_taxonomy_refactor_20260627`; the dataclasses moved to per-system files (`src/mma.py`, `src/project_files.py`, `src/type_aliases.py`, etc.). The 48-site count reflects the pre-refactor state. **`src/api_hook_client.py`**: HTTP request/response payloads use `Metadata` (the canonical "API payload" shape). diff --git a/conductor/tracks/directive_hotswap_harness_20260627/plan.md b/conductor/tracks/directive_hotswap_harness_20260627/plan.md index d2ee6574..00eb3661 100644 --- a/conductor/tracks/directive_hotswap_harness_20260627/plan.md +++ b/conductor/tracks/directive_hotswap_harness_20260627/plan.md @@ -101,17 +101,17 @@ Each task creates one or more `conductor/directives//v1.md` files. The v1 - [ ] **Step 1.1: Harvest §17 banned patterns (7 directives)** **Files to read:** -- `conductor/code_styleguides/python.md:216-409` (§17 Banned Patterns — the 7 banned patterns + §17.7 boundary exception + §17.8 enforcement + §17.9 local imports + §17.10 enforcement inventory) +- `conductor/code_styleguides/python.md:243-473` (§17 Banned Patterns — the 7 banned patterns + §17.7 boundary exception + §17.8 enforcement + §17.9 local imports + §17.10 enforcement inventory) **Directives to create:** -1. `conductor/directives/ban_dict_any/v1.md` — source: `python.md:220-237` (§17.1). Content: the `dict[str, Any]` ban + before/after examples + the boundary exception cross-ref. -2. `conductor/directives/ban_any_type/v1.md` — source: `python.md:239-250` (§17.2). Content: the `Any` ban + before/after. -3. `conductor/directives/ban_optional_returns/v1.md` — source: `python.md:252-272` (§17.3). Content: the `Optional[T]` return ban + the `Result[T]` replacement pattern. -4. `conductor/directives/ban_hasattr_dispatch/v1.md` — source: `python.md:274-299` (§17.4). Content: the `hasattr()` for entity type dispatch ban + the typed Union alternative. -5. `conductor/directives/ban_getattr_dispatch/v1.md` — source: `python.md:301-311` (§17.5). Content: the `getattr(x, 'field', default)` for type dispatch ban. -6. `conductor/directives/ban_dict_get_on_known_fields/v1.md` — source: `python.md:313-323` (§17.6). Content: the `.get('field', default)` on a `dict[str, Any]` ban + direct attribute access alternative. -7. `conductor/directives/boundary_layer_exception/v1.md` — source: `python.md:325-327` (§17.7). Content: the ONE exception — the wire boundary (TOML/JSON parse) where `dict[str, Any]` is allowed. +1. `conductor/directives/ban_dict_any/v1.md` — source: `python.md:247-264` (§17.1). Content: the `dict[str, Any]` ban + before/after examples + the boundary exception cross-ref. +2. `conductor/directives/ban_any_type/v1.md` — source: `python.md:266-277` (§17.2). Content: the `Any` ban + before/after. +3. `conductor/directives/ban_optional_returns/v1.md` — source: `python.md:279-299` (§17.3). Content: the `Optional[T]` return ban + the `Result[T]` replacement pattern. +4. `conductor/directives/ban_hasattr_dispatch/v1.md` — source: `python.md:301-326` (§17.4). Content: the `hasattr()` for entity type dispatch ban + the typed Union alternative. +5. `conductor/directives/ban_getattr_dispatch/v1.md` — source: `python.md:328-338` (§17.5). Content: the `getattr(x, 'field', default)` for type dispatch ban. +6. `conductor/directives/ban_dict_get_on_known_fields/v1.md` — source: `python.md:340-350` (§17.6). Content: the `.get('field', default)` on a `dict[str, Any]` ban + direct attribute access alternative. +7. `conductor/directives/boundary_layer_exception/v1.md` — source: `python.md:352-354` (§17.7). Content: the ONE exception — the wire boundary (TOML/JSON parse) where `dict[str, Any]` is allowed. **Variant header format** (use for ALL v1 files): ```markdown @@ -131,18 +131,18 @@ will test alternative encodings (rationale-first, before/after, tabular) against - [ ] **Step 1.2: Harvest §17.9 import/aliasing bans (3 directives)** **Files to read:** -- `conductor/code_styleguides/python.md:336-409` (§17.9 local imports + aliasing + repeated from_dict) +- `conductor/code_styleguides/python.md:364-443` (§17.9 local imports + aliasing + repeated from_dict) **Directives to create:** -8. `conductor/directives/ban_local_imports/v1.md` — source: `python.md:336-360` (§17.9a). Content: local imports inside functions are banned + the `try/except ImportError` exception + the vendor-SDK-warmup whitelist. +8. `conductor/directives/ban_local_imports/v1.md` — source: `python.md:364-443` (§17.9a). Content: local imports inside functions are banned + the `try/except ImportError` exception + the vendor-SDK-warmup whitelist. 9. `conductor/directives/ban_prefix_aliasing/v1.md` — source: `python.md` (§17.9b, within the 336-409 range). Content: `import X as _X` aliasing-for-naming-convenience is banned. 10. `conductor/directives/ban_repeated_from_dict/v1.md` — source: `python.md` (§17.9c, within the 336-409 range). Content: repeated `.from_dict()` calls in the same expression are banned. - [ ] **Step 1.3: Harvest error handling conventions (2 directives)** **Files to read:** -- `conductor/code_styleguides/error_handling.md:22-56` (the 5 patterns) + `error_handling.md:212-242` (hard rules) + `error_handling.md:274-311` (boundary types) +- `conductor/code_styleguides/error_handling.md:22-56` (the 5 patterns) + `error_handling.md:212-264` (hard rules) + `error_handling.md:284-365` (boundary types) **Directives to create:** @@ -153,7 +153,7 @@ will test alternative encodings (rationale-first, before/after, tabular) against **Files to read:** - `conductor/code_styleguides/data_oriented_design.md:176-215` (§8.5 Python Type Promotion Mandate + §8.6 Boundary Layer + §8.7 C11 framing) -- `conductor/code_styleguides/type_aliases.md:40-81` (Metadata boundary type + when to promote + when NOT to promote) +- `conductor/code_styleguides/type_aliases.md:13-87` (the canonical alias set + the extended per-aggregate dataclasses table) + `type_aliases.md:89-160` (Decision Pattern 2.5 — when to promote to its own dataclass) + `type_aliases.md:284-365` (boundary types + anti-patterns) **Directives to create:** @@ -166,8 +166,8 @@ will test alternative encodings (rationale-first, before/after, tabular) against **Files to read:** - `conductor/code_styleguides/python.md:7-21` (§1 Indentation + §2 Type Annotations) - `conductor/code_styleguides/python.md:64-71` (§8 AI-Agent Specific Conventions — no comments, no diagnostic noise) -- `conductor/code_styleguides/python.md:185-199` (§13 Vertical Compaction) -- `conductor/code_styleguides/python.md:175-184` (§12 SDM) +- `conductor/code_styleguides/python.md:202-211` (§12 SDM) +- `conductor/code_styleguides/python.md:212-224` (§13 Vertical Compaction) - `conductor/workflow.md:5-20` (Code Style section) **Directives to create:** @@ -176,14 +176,14 @@ will test alternative encodings (rationale-first, before/after, tabular) against 17. `conductor/directives/no_comments_in_body/v1.md` — source: `python.md:66` + `AGENTS.md:56`. Content: no comments in source code; documentation lives in `/docs`. Only comment on *why* when non-obvious. 18. `conductor/directives/no_diagnostic_noise/v1.md` — source: `python.md:70` + `AGENTS.md` "No Diagnostic Noise in Production" section. Content: no `sys.stderr.write("[XYZ_DIAG] ...")` in production code. Diag goes to log files or temp scripts. 19. `conductor/directives/type_hints_required/v1.md` — source: `python.md:24-31` + `product-guidelines.md:58`. Content: mandatory strict type hints for all parameters, return types, and global variables. -20. `conductor/directives/sdm_dependency_tags/v1.md` — source: `python.md:175-184` (§12) + `product-guidelines.md:59`. Content: Structural Dependency Mapping tags (`[C: ...]`, `[M: ...]`, `[U: ...]`) in docstrings for AI-assisted impact analysis. +20. `conductor/directives/sdm_dependency_tags/v1.md` — source: `python.md:202-211` (§12) + `product-guidelines.md:59`. Content: Structural Dependency Mapping tags (`[C: ...]`, `[M: ...]`, `[U: ...]`) in docstrings for AI-assisted impact analysis. - [ ] **Step 1.6: Harvest file/taxonomy conventions (3 directives)** **Files to read:** - `AGENTS.md:62-76` (File Size and Naming Convention HARD RULE) - `conductor/workflow.md:45` (File Naming Convention HARD RULE) -- `conductor/code_styleguides/python.md:205-215` (§15 Modular Controller Pattern) +- `conductor/code_styleguides/python.md:234-241` (§15 Modular Controller Pattern) **Directives to create:**