ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

docs(styleguides+harness-plan): fix stale models.py refs + harness plan line drift

Browse Source 
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).
This commit is contained in:
Edward R. Gonzalez
2026-07-02 19:31:32 -04:00
parent 46f0ec152a
commit 8b7b8b96c7
5 changed files with 31 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
conductor/code_styleguides/agent_memory_dimensions.md
+2 -3
View File
@@ -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) |
conductor/code_styleguides/config_state_owner.md
+3 -1
View File
@@ -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
conductor/code_styleguides/python.md
+2 -2
View File
@@ -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
conductor/code_styleguides/type_aliases.md
+8 -3
View File
@@ -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).
conductor/tracks/directive_hotswap_harness_20260627/plan.md
+16 -16
View File
@@ -101,17 +101,17 @@ Each task creates one or more `conductor/directives/<name>/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:**