chore: strengthen Python static analysis

[AlexStocks]

Which issue or RFC does this PR close?

N/A — this is a focused engineering-hardening change with no linked issue or RFC.

Rationale for this change

The default ty configuration leaves several high-value diagnostics disabled. Enabling them against the production source exposed missing override declarations and control-flow paths whose variables were not provably initialized. Those gaps reduce refactor safety and delay feedback until runtime or review.

This change makes the validated rules part of the normal development gate while keeping the scope limited to static safety. It does not change the public HTTP contract, persisted formats, or PowerContext domain behavior.

What changes are included in this PR?

• enable selected ty rules for possible unresolved references, missing override declarations, raw generics, optional imports/attributes, dynamic bases, and division by zero;
• run ty from prek with uv run --locked, and remove the duplicate ty invocation from make check;
• add explicit @override declarations across production inheritance boundaries;
• make Client tracing span initialization and Memory search tracing state statically definite;
• enable the currently clean Ruff ASYNC, DTZ, LOG, and PLE rule families;
• keep intentional test-only lint exceptions line-scoped and documented;
• declare the existing typing-extensions runtime dependency directly where override is imported;
• synchronize the Bub harness lock and type-check it against its declared Python 3.12 minimum.

Tests only received type annotations or explicit initialization needed by the stricter checker; no assertions or observable test scenarios were changed.

Are there any user-facing changes?

No. There are no public API, HTTP/MCP contract, configuration, persistence, or migration changes.

How was this change tested?

• make check
• make contract-test — 29 passed
• uv run --locked ty check --error all src/powercontext integrations/claude-code integrations/codex integrations/hermes
• make harness-sync
• make harness-check — 6 passed
• affected-path pytest selection on Windows — 88 passed
• make unit-test under Linux/WSL Python 3.13 — 593 passed, 1 skipped
• make e2e-test under Linux/WSL Python 3.13 — 45 passed, 12 skipped
• git diff --check origin/master...HEAD

Real Codex/provider E2E remains opt-in and was not part of the acceptance gate for this static-analysis change.

AI usage statement

OpenAI Codex (GPT-5) was used to inspect the repository, implement the change, run validation, and prepare this PR. A separate read-only Codex review pass checked the final diff before publication.

[Copilot]

Pull request overview

This PR strengthens the project’s static-analysis gate by tightening ty and Ruff configurations, wiring ty into the pre-commit/prek workflow, and making production code changes required to satisfy the stricter diagnostics (notably explicit @override usage and statically definite initialization in tracing-related paths).

Changes:

• Enabled additional ty rule checks and Ruff lint families (ASYNC, DTZ, LOG, PLE) via pyproject.toml, with targeted test-only exceptions.
• Moved ty check into prek/pre-commit (and removed the duplicate make check invocation), plus updated harness checking for a Python 3.12 minimum where applicable.
• Added typing-extensions dependency and applied @override across multiple inheritance boundaries; adjusted client span and memory-search tracing state to be statically definite.

Reviewed changes

Copilot reviewed 22 out of 25 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
pyproject.toml	Adds typing-extensions runtime dep; configures ty rules/overrides and expands Ruff lint selection.
.pre-commit-config.yaml	Adds a local ty check hook executed via uv run --locked.
Makefile	Removes standalone ty run from check; pins Bub harness ty invocation to Python 3.12.
uv.lock	Locks in typing-extensions as a direct dependency.
src/powercontext/client/client.py	Makes request spans start before try to ensure definite initialization for error paths.
src/powercontext/builtin/runtime/application.py	Ensures tracing attributes use a definitely-initialized search_mode.
src/powercontext/builtin/runtime/composition.py	Adds @override on projector methods crossing inheritance boundaries.
src/powercontext/builtin/handoff_report/catalog_store.py	Adds @override on CatalogPage.__repr__/__eq__.
src/powercontext/server/access.py	Adds @override to MCP middleware on_request.
src/powercontext/server/logging.py	Adds @override to logging filter/formatter overrides.
src/powercontext/server/mcp.py	Adds @override to httpx.ASGITransport.handle_async_request.
src/powercontext/server/metrics.py	Adds @override to MCP metrics middleware on_request.
src/powercontext/server/tracing.py	Adds @override to tracer/middleware overrides for stricter static checking.
tests/test_handoff_report_models.py	Adds a scoped DTZ001 ignore for intentional invalid datetime input in tests.
tests/builtin/runtime/test_scheduler.py	Tightens PowerContext generics in test helper types.
tests/integrations/test_hermes_provider.py	Adds explicit Any typing for stricter type checking in fakes.
tests/e2e/real_experience_skill/harness.py	Makes configured-journey state statically definite; documents intentional ASYNC lint exception.
integrations/hermes/plugins/powercontext/client.py	Introduces a type-check-only override import with a runtime no-op fallback for compatibility.
integrations/codex/plugins/powercontext/pyproject.toml	Adds typing-extensions dependency for the Codex plugin package.
integrations/codex/plugins/powercontext/uv.lock	Updates plugin lockfile to include typing-extensions.
integrations/codex/plugins/powercontext/settings.py	Adds @override for settings source hooks/customization points.
integrations/codex/plugins/powercontext/hooks/recall.py	Adds @override for redirect handler override.
integrations/claude-code/plugins/powercontext/hooks/user_prompt_submit.py	Adds type-check-only override import with runtime no-op fallback and uses it on redirect handler override.
e2e/bub/uv.lock	Locks in typing-extensions for the Bub harness environment.
e2e/bub/src/powercontext_e2e/harbor_agent.py	Uses typing.override (Py3.12+) for Bub harness agent method override.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.