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

docs: fix 6 contradictions from CONTRADICTIONS_REPORT_20260627 (C5/C6/C17/C19/C2)

Browse Source 
Six fixes for the c11_python doc sync (chronology row 3):

- C5 (Result notation): Result[str, ErrorInfo] -> Result[str] at
  docs/guide_ai_client.md lines 452 + 469; also error_handling.md
  line 801 (historical deprecation section).
- C6 (RAGChunk schema): docs/guide_models.md lines 343-349 corrected
  to match src/rag_engine.py:19-25 (id, document, path, score, metadata).
- C17 (type_aliases.md table): rewrote alias table to reflect post-2026-06-25
  reality (Metadata is @dataclass(frozen=True, slots=True) with 36 fields;
  11 per-aggregate dataclasses listed with source locations; removed
  stale 'underlying type is dict[str, Any]' claim at line 73 + the
  'keep Metadata as dict[str, Any]' claim at line 81).
- C19 (OBLITERATE principle): added 'OBLITERATE Principle' section to
  error_handling.md after Migration Playbook; clarified in Hard Rules
  that argument types that may be None (caller choice) are NOT banned.
- C2 (audit script name): docs/AGENTS.md references updated to point
  to scripts/audit_optional_returns.py (the all-src/ successor to
  scripts/audit_optional_in_3_files.py).

Also: docs/reports/CONTRADICTIONS_REPORT_20260627.md — the contradictions
index that drives these fixes. Kept for reference.

C16 + C18 were already addressed in commit 770c2fdb (python.md §10
Documented Exceptions table + §17.10 audit inventory).
This commit is contained in:
ed
2026-06-26 09:24:38 -04:00
parent 770c2fdb32
commit a101d34656
6 changed files with 426 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/AGENTS.md
+2 -2
View File
@@ -34,7 +34,7 @@ The canonical mandate is in [`conductor/code_styleguides/data_oriented_design.md
4. **The enforcement audit scripts** — the project-level enforcement set:
- `scripts/audit_weak_types.py --strict` — flags `dict[str, Any]`, `Any`, anonymous tuples
- `scripts/audit_optional_in_3_files.py --strict` — flags `Optional[T]` (extended to all `src/*.py` per the c11_python track)
- `scripts/audit_optional_returns.py --strict` — flags `Optional[T]` return types in ALL `src/*.py` (post-2026-06-27 successor to `audit_optional_in_3_files.py`)
- `scripts/audit_exception_handling.py --strict` — the data-oriented error handling convention
- `scripts/audit_main_thread_imports.py` — always strict; the import graph gate
- `scripts/audit_no_models_config_io.py` — the config-I/O ownership gate
@@ -45,7 +45,7 @@ The canonical mandate is in [`conductor/code_styleguides/data_oriented_design.md
```bash
# Run before claiming "done"
uv run python scripts/audit_weak_types.py
uv run python scripts/audit_optional_in_3_files.py
uv run python scripts/audit_optional_returns.py
uv run python scripts/audit_exception_handling.py
uv run python scripts/audit_main_thread_imports.py
uv run python scripts/audit_no_models_config_io.py