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).
TIER-2 READ conductor/code_styleguides/error_handling.md before Phase 12.0.1.
The 7 sections reviewed: (1) The 5 Patterns, (2) Decision Tree, (3)
Anti-Patterns, (4) Hard Rules, (5) Boundary Types, (6) The Broad-Except
Distinction, (7) AI Agent Checklist.
12.0.1 changes to the styleguide:
(A) Add 'Drain Points: Where Result[T] Propagation Terminates' section
after 'Boundary Types'. Codifies the user's principle (2026-06-17):
'IF ANY PLACE HAS A ERROR LOG IT ALSO NEEDS A RESULT[T]. RESULT[T]
PROPOGATES UNTIL IT REACHED A DRAIN POINT WHERE THE ERROR CAN BE
HANDLED APPROPRIATELY WITHOUT CRASHING THE APP.'
The 5 drain point patterns: HTTP error response, GUI error display,
intentional app termination, telemetry emission, bounded retry.
Each has a code example and a 'NOT a drain' counter-example.
Explicitly states: sys.stderr.write(...) alone is NOT a drain.
(B) Update 'The Broad-Except Distinction' table to add an explicit row:
'narrow except + log only | INTERNAL_SILENT_SWALLOW | Violation'.
Adds 5 new rows for the 5 drain-point patterns (all Heuristic D
compliant). Makes Heuristic #19 laundering impossible by spelling
out narrow+log = violation.
(C) Add Rule #0 to the AI Agent Checklist: 'READ THIS STYLEGUIDE
FIRST'. Forces every agent to read end-to-end before writing
try/except code; acknowledge the read in the commit message.
Cites the Phase 10 LAUNDERING HEURISTICS incident as the reason.
Doc consistency: guide_ai_client.md, guide_app_controller.md, and
the error_handling styleguide now reference the new symbol name.
Also fixes two consistency issues in error_handling.md introduced by
the mechanical rename:
1. The 'Deprecation: send -> send_result' section (lines 623-642) was
rewritten as a 'Historical deprecation (added 2026-06-15, reverted
2026-06-16)' note that points to the relevant track specs.
2. Line 204 (the 'Current State Audit' summary for src/ai_client.py)
had a self-contradictory claim ('send() is the new public API;
send() is @deprecated') after the rename. Updated to describe
the canonical public API.
Historical archives (conductor/tracks/*/spec.md, conductor/tracks/*/plan.md,
docs/reports/*) are NOT modified - they document the 2026-06-15
public_api_migration decision and stay as historical record.
ed