HYP-203 Align handler docs with direct composition

[proboscis]

概要

HYP-203 は、deprecated な WithHandler 互換 shim を現行の handler 合成 API として README / docs / examples が案内していた問題を直します。

変更内容

• README.md と現行 docs の handler 合成例を handler(program) の直接呼び出しへ更新しました。
• examples/ の WithHandler(...) 例を、raw dispatcher を Program -> Program installer に変換してから直接呼ぶ形へ更新しました。
• packages/doeff-core-effects/doeff_core_effects/handlers.py の core handler factory が Program -> Program installer を返すようにし、README の標準例が警告なしで実行できるようにしました。
• tests/test_docs_withhandler_contract.py に docs / examples guard と canonical snippet の警告なし検証を追加しました。
• packages/doeff-hy/src/doeff_hy/macros.hy の defhandler 説明文も直接呼び出しに揃えました。

境界

• HYP-168 の default_handlers / async_run drift は別課題として残しています。この PR では WithHandler shim を推奨合成 API として案内しないことに絞っています。
• HYP-158 の return_clause rule と HYP-197 の Hy production handler signature drift は対象外です。
• WithHandler 互換 shim と WithHandlerType は削除していません。互換 shim は deprecation warning を維持し、低レベル構築は WithHandlerType を使う説明に整理しています。

確認したこと

• uv run pytest tests/test_docs_withhandler_contract.py -q
• uv run pytest tests/test_withhandler_shim_deprecation.py -q
• uv run python -W default で writer()(state()(reader(...)(program))) 型の標準例が DeprecationWarning なしで 1 を返すことを確認
• rg -n "WithHandler\\(|handler=\\.\\.\\.|default_handlers\\(|async_run\\(" README.md docs -g '*.md' で、WithHandler(...) の残存が archival/spec docs だけになったことを確認
• uv run pytest -q は 836 passed, 84 skipped

未解消の既存状態

• uv run pyright は既存の doeff/cli/discovery.py:57 の Indexer import symbol エラーで停止しました。今回の変更箇所ではありません。
• ruff の全体実行は既存の広範な import / re-export / 複雑度指摘を拾うため、今回追加・変更した docs guard と handler wrapper 周辺の focused check を確認しました。