conductor(track): Phase 12 prerequisites - tier-2 MUST read styleguide; styleguide must be updated to be aware of drain points

This commit is contained in:
ed
2026-06-18 09:03:58 -04:00
parent 7c1d84623c
commit 6b7fb9cdb8
4 changed files with 70 additions and 1 deletions
@@ -69,12 +69,16 @@ sites** across the codebase.
> **Phase 12 Update (2026-06-17, REJECTED Phase 11):**
> **THE USER'S PRINCIPLE:** "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 APP SHOULD ALMOST NEVER CRASH UNLESS SOMETHING CRITICAL FAILS THAT PREVENTS IT FROM ACTUALLY OPERATING WITH ITS FEATURES."
>
> **THE USER'S DIRECTIVE ON THE STYLEGUIDE:** "make sure tier 2 is required to read that styleguide and make sure to update the style guide to be aware of the concept of a drain point, which just makes explicit a place where result[t]"
>
> Phase 11 was REJECTED for 3 reasons:
> 1. **Heuristic #19 is LAUNDERING.** The "narrow + log = compliant" pattern is WRONG. Logging is NOT a drain. Phase 11 left Heuristic #19 in place; 6 sites in the "14 already compliant" claim were Laundering via Heuristic #19. Phase 12.1 REMOVES Heuristic #19.
> 2. **The audit-script `visit_Try` walker is BUGGY.** It does NOT recurse into `node.body` (the try body itself), so nested Trys are silently dropped. I verified: `src/api_hooks.py` has 23 actual try/except nodes but the audit reports only 5 — a gap of 18 sites, 12+ of which are silent-fallback violations. Phase 12.2 FIXES this bug.
> 3. **Tier-2 misclassified 2 sites.** The claims of "HTTP request handlers; classified `INTERNAL_COMPLIANT` via Heuristic #19" for `api_hooks.py:451` and `:824` are wrong about which heuristic applies. The actual code at L451 is `except (OSError, ValueError) as e: self.send_response(500)` (narrow + HTTP response, NOT a Heuristic #19 log call). The actual code at L824 is `except (OSError, ValueError) as e: import traceback; traceback.print_exc(file=sys.stderr)` (narrow + traceback, NOT a Heuristic #19 log call). Phase 12.6.1 migrates these.
>
> **Phase 12 ACTIONS:**
> - 12.0: TIER-2 MUST READ `conductor/code_styleguides/error_handling.md` end-to-end BEFORE any Phase 12 code work. NO CODE; the read is acknowledged in the commit message of 12.0.1.
> - 12.0.1: UPDATE `error_handling.md` with 3 changes: (A) add a "Drain Points" section with 5 patterns; (B) update the "Broad-Except Distinction" table to explicitly say `narrow + log = INTERNAL_SILENT_SWALLOW` violation (prevents Heuristic #19 regression); (C) add a MUST-READ rule to the AI Agent Checklist.
> - 12.1: REMOVE Heuristic #19 (narrow+log laundering)
> - 12.2: FIX the visit_Try audit bug (2-line change to recurse into node.body)
> - 12.3: ADD Heuristic D (True Drain-Point Recognition) with 5 patterns: HTTP error response, GUI error display, intentional app termination, telemetry emission, retry-with-bounded-attempts