From c9c5abfbae2513cfc152ac636086c0cfbd3c6530 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sun, 21 Jun 2026 13:01:19 -0400 Subject: [PATCH] docs(product-guidelines): add Data Structure Conventions section --- conductor/product-guidelines.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md index 6df3603b..e53f5306 100644 --- a/conductor/product-guidelines.md +++ b/conductor/product-guidelines.md @@ -67,8 +67,8 @@ This convention is established incrementally. The 2026-06-11 `data_oriented_error_handling_20260606` track applies it to `src/mcp_client.py`, `src/ai_client.py`, and `src/rag_engine.py`. Future tracks will apply it to the remaining `src/` files -(`src/app_controller.py`, `src/models.py`, `src/project_manager.py`, etc. — -see `conductor/tracks/data_oriented_error_handling_20260606/spec.md` §12.2 +(`src/app_controller.py`, `src/models.py`, `src/project_manager.py`, etc. - +see `conductor/tracks/data_oriented_error_handling_20260606/spec.md` 12.2 for the prioritized list). **Audit:** the convention is enforced via @@ -81,6 +81,29 @@ report or `--json` for machine-readable output. The audit classifies each violation + 1 suspicious + 1 unclear); see the styleguide's "Audit Script" section for the full taxonomy. +## Data Structure Conventions + +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`, +`History`, `FileItem`, `FileItems`, `ToolDefinition`, `ToolCall`, +`CommsLogCallback`) cover the 86% of common patterns. The canonical +reference is in +[`conductor/code_styleguides/type_aliases.md`](code_styleguides/type_aliases.md). + +**Field-level schema information is in `docs/type_registry/`.** This is +auto-generated by `scripts/generate_type_registry.py` (runs as part of +track completion; CI runs `--check` to detect drift). When the LLM +needs the fields of a type, it reads the corresponding registry file +(e.g., `docs/type_registry/src_models.md` for `src/models.py`). + +This convention is established by the +`data_structure_strengthening_20260606` track (2026-06-06). The audit +script `scripts/audit_weak_types.py` is the gatekeeper: it counts +anonymous `dict[str, Any]` / `list[dict[...]]` / `Tuple[...]` sites and +fails CI if new ones are introduced (`--strict` mode against the +`scripts/audit_weak_types.baseline.json` baseline). + ### AI Agent Obligations (Added 2026-06-16) AI agents writing code in this codebase MUST follow the data-oriented