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

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:
ed
2026-07-02 19:31:32 -04:00
parent 46f0ec152a
commit 8b7b8b96c7
5 changed files with 31 additions and 25 deletions
@@ -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) |
@@ -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
+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
+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).