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

docs(product-guidelines): add Data Structure Conventions section

Browse Source
This commit is contained in:
Edward R. Gonzalez
2026-06-21 13:01:19 -04:00
parent 7a52fca588
commit c9c5abfbae
1 changed files with 25 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
conductor/product-guidelines.md
+25 -2
View File
@@ -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