docs(20.2): record live validation and close the state item

317 live integration tests pass against HEAD in 2m30s. CI matrix extended to
Python 3.14 and green. Closes the malformed-JSON open item, noting the sweep
found the problem wider than the original note assumed (108 uncovered tools,
not 7 mislabelling modules) and that Codex surfaced two further defects in
the fix itself.

Author: mariomeyer

.planning/STATE.md

@@ -2,13 +2,13 @@
 gsd_state_version: 1.0
 milestone: v1.1
 milestone_name: Statistics Canada + Datastore
-current_phase: 20
-current_phase_name: Finish integration de-masking and fix the failures it exposed
+current_phase: "20.2"
+current_phase_name: Normalize tool error handling and guard malformed upstream JSON
 status: awaiting_merge
-stopped_at: "Phase 20.1 complete; PR #2 open with all four CI gates green"
-last_updated: "2026-07-26T02:32:53.467Z"
-last_activity: 2026-07-25
-last_activity_desc: Phase 20.1 executed end to end
+stopped_at: "Phase 20.2 complete; PR #3 green on 3.12/3.13/3.14, Codex findings addressed"
+last_updated: "2026-07-26T04:00:00.000Z"
+last_activity: 2026-07-26
+last_activity_desc: Phase 20.2 executed and verified; 317 live tests green
 progress:
   total_phases: 36
   completed_phases: 16
@@ -28,10 +28,12 @@ See: .planning/PROJECT.md (updated 2026-04-07)
 
 ## Current Position
 
-Phase: 20.1 of 36 — COMPLETE and MERGED to main (PR #2, merge commit 98dee90)
-Plan: 6 of 6 complete
-Status: next is Phase 20.2 (run /gsd-plan-phase 20.2)
-Last activity: 2026-07-26 — Phase 20.1 merged; all four CI gates green
+Phase: 20.2 of 36 — COMPLETE, awaiting merge (PR #3)
+Plan: 1 of 1 complete
+Status: PR #3 green on Python 3.12/3.13/3.14; both Codex findings fixed; next is Phase 21
+Last activity: 2026-07-26 — Phase 20.2 executed and verified; 317 live tests green
+
+Phase 20.1 is COMPLETE and MERGED to main (PR #2, merge commit 98dee90).
 
 Progress: [████░░░░░░] 44%
 
@@ -94,7 +96,7 @@ Open defect (found 2026-07-26, deferred to its own phase):
   behind an env-var key like Manitoba 511. Alberta AHS, parks, forest-area and
   Saskatchewan/Manitoba Hub services were probed at the same time and are healthy.
 
-- **Malformed-JSON masking is broader than the spot Codex flagged.** → **now Phase 20.2.**
+- ~~**Malformed-JSON masking is broader than the spot Codex flagged.**~~ → **CLOSED by Phase 20.2** (PR #3). The sweep found the problem was wider than this note assumed: 108 of 271 tools had no catch-all at all, not just 7 modules with a mislabelling `ValueError` arm. Codex then found two further defects in the fix itself — `upstream_guard` was never a true catch-all (a `KeyError` still escaped), and `pydantic.ValidationError` also subclasses `ValueError`, so upstream schema drift was blamed on the caller. Both fixed. Original note kept below for the record:
   `upstream_guard` is fixed, which covers drug_database and nutrient_file (they use
   their own clients). But `shared/http.py:api_get` returns `response.json()` with no
   decode guard, and ~40 `except ValueError -> INVALID_INPUT` arms across statcan,

.planning/phases/20.2-normalize-tool-error-handling-and-guard-malformed-upstream-j/20.2-VERIFICATION.md

@@ -31,6 +31,8 @@ failure — never as caller error, never as an escaped exception.
 | 9 | `upstream_guard` really is a catch-all | ✓ VERIFIED | `test_upstream_guard_really_is_a_catch_all` raises a custom exception type through it |
 | 10 | Upstream schema drift is not caller error | ✓ VERIFIED | `test_pydantic_validation_error_is_upstream_not_caller_error` |
 | 11 | Coverage stays above the 95% gate | ✓ VERIFIED | 97.09% |
+| 12 | Guards behave against real APIs | ✓ VERIFIED | 317 live integration tests passed in 2m30s against HEAD |
+| 13 | Supported Python versions actually tested | ✓ VERIFIED | CI matrix now 3.12 / 3.13 / 3.14, all green |
 
 ## Requirements Coverage
 
@@ -86,6 +88,21 @@ Both were verified against the runtime before acting (`pydantic.ValidationError.
 and the guard's actual `except` list), and both fixes were confirmed non-vacuous
 by reverting `envelope.py` — all 6 new tests fail without it.
 
+## Live validation
+
+`uv run pytest tests/integration/ -m integration -k "not drug and not nutrient"`
+against HEAD: **317 passed, 23 deselected, 2m30s.** Zero failures, so decorating
+108 tools changed no live behaviour on the success path while closing the leak
+on the failure path.
+
+Drug/nutrient were excluded because the Phase 20.1 caveat still applies (Health
+Canada rate-limits them under full-suite load; they pass in isolation). Their 16
+tools were already guarded before this phase, so they are not what 20.2 changed.
+
+Note on Python versions: every local check in this phase ran on **3.14.4**, while
+CI proved only 3.12 and 3.13 despite `requires-python = ">=3.12"`. 3.14 was added
+to the matrix and passes; the stale classifiers were corrected at the same time.
+
 ## Known limitation
 
 `upstream_guard` reads `lang` from `kwargs`, so a tool invoked with `lang`