[tommasobolis]

Closes #1431

Part of the 0.2.0 review epic #1414.

Summary

• Adds a ## 0.2.0 section to MIGRATION.md. It uses 0.1.2's layout: an intro that groups the sections, then numbered Who / Symptom / Fix entries for changes that affect code written against 0.1.3, then (not breaking) entries. The numbered list is meant to seed the Release's "## Breaking changes" section.
  1. A CIBA approval response is now GatewayApprovalPending (was AuthError) or GatewayApprovalDenied (classify: type the OBO policy's CIBA authorization_pending instead of AuthError #1320).
  2. Model Armor and CrowdStrike AIDR blocks are now ContentSafetyBlocked (were PolicyViolation(policy="unknown")) (refusals: type the Google Model Armor Guardrails rejection #1178, refusals: type the CrowdStrike AIDR Guardrails rejection #1176).
  3. classify is a Classifier instance with register() (feat(classify): registry so custom gateway policies become typed exceptions #1152).
  4. donkey publish and donkey verify now run, and no longer exit 3.
  5. The registry, discovery and ToolSet calls reach Anypoint instead of raising NotImplementedError. The entry lists what is still blocked.
  6. discover() defaults to governed=True (ADR 0017).
  7. donkey_kit.experimental.GovernanceCriteria is deprecated in favour of donkey_kit.GovernanceCriteria.
  8. The [cli] floors rise to typer 0.26.0 and rich 13.8.0. typer ≥0.26 no longer installs click.
  9. The mcp and a2a extras are back, and [all] and [adk] install more.
  10. An AgentKilled stops that Donkey for good.
  11. refusal_translator leaves two adapters' __all__.
  12. A configured URL with a user name or password raises ConfigError, whatever DONKEY_ALLOW_HTTP says (core: refuse a user name or password in configured endpoint URLs #1478).
• Not-breaking entries:
  • budget-header hardening (budget: an out-of-range reset header crashes send() with OverflowError #1444, budget + telemetry: state and test the concurrency contract under parallel fan-out #311);
  • the ADK factories return subclasses (framework-release: google-adk 2.12.0 → 2.13.0 #1207);
  • the OpenAI Agents SDK becomes a deep adapter, with its tracing opt-out (docs: warn that Agents SDK tracing exports prompts to OpenAI by default #1434);
  • new public names.
• "If you used a 0.2.0 pre-release" sub-list. This is a clearly labelled list for changes that only affect code written against 0.2.0.devN, because the surface was new or blocked in 0.1.3. Examples: as_user(token=), ToolSet.openai_agents(), --agent-version, the --json format keys, the approval helpers, requester identity, the https gateway rule, the per-client Approvals API (hitl: settle the Approvals API — typed errors, naming and scope #1423), and the install-hint ImportError from the ADK and LangGraph helpers (adk: raise the install-hint ImportError from the new ADK helpers #1440, langgraph: raise the install-hint ImportError from approve(), reject() and approval_interrupt() #1502).
• Moves the misfiled budget: read the upstream provider's x-ratelimit-*-requests window as a separate source #1025 sentence. UpstreamQuota/UpstreamWindow comes out of 0.1.2's "New exports" and goes into 0.2.0's "New public names". It shipped in feat(budget): read the upstream provider's rate-limit window as its own source (BG §1.3) #1246, after 0.1.3.
• Adds a short ## 0.1.3 section. Its Release had no breaking changes, but it changed two behaviours a reader would notice: typed refusals through ADK model() (feat(refusals): bridge typed refusals through ADK model() (LiteLLM) #969) and the CA/JP control-plane hosts (Verify Anypoint control-plane region hosts for EU, CA and JP Hyperforce #22). Every other release has a section, so the gap read as "nothing changed".
• States that 0.1.2's deprecated names still work and still warn in 0.2.0. GovernanceCriteria is the exception.
• Sources. Each entry was checked against develop, and the code won where it disagreed with a PR body or the issue:
  • ExchangeRegistry.warm() is still blocked; only donkey.tools.warm() runs.
  • Publication(descriptor="auto:static") does not raise. Only derive_descriptor(mode="auto:static") raises ValueError.
  • A registered classify rule's class needs its own remediation.
• Late entries, added after rebasing onto develop:
  • core: refuse a user name or password in configured endpoint URLs #1478: new breaking entry 12.
  • tools: apply the ADR 0005 endpoint check to the gateway credential on discovered servers #1479 / ADR 0019: the gateway credential is held back from a project-file base_url. It is a note on entry 5, because those calls raised NotImplementedError in 0.1.3, plus a pre-release bullet. This follows the tools: require https on MCP and A2A endpoints resolved from the gateway #1417 https rule's precedent.
  • hitl: settle the Approvals API — typed errors, naming and scope #1423: pre-release bullets for the per-client registry, the typed approval errors and the whole-server require_approval() ConfigError. Entry 1 now notes that GatewayApprovalDenied is also an ApprovalError.
  • refactor: remove the registry→tools reach-in and decouple Strands refusals #1446 / api: ship ToolsFacade.live_tools and live_card as Provisional #1499: GovernedToolHook, plus live_tools() / live_card() marked Provisional (ADR 0020), under New public names.
  • adk: raise the install-hint ImportError from the new ADK helpers #1440 / langgraph: raise the install-hint ImportError from approve(), reject() and approval_interrupt() #1502: the helpers now raise ImportError, the parent class, so except ModuleNotFoundError no longer catches it. fix(adk): raise the install-hint ImportError from the module-level helpers #1492's body says the opposite.
  • scanner: a publish rerun writes the Exchange page without "Changes since" #1481: omitted. A rerun's "Changes since" page needs no code change, and this file lists only what can affect code.
• Final entries, from chore: 0.2.0 review hygiene sweep (CLI, simulator, ADK, ledger rows) #1447 and agent_framework: policy_middleware() raises NotImplementedError instead of the install hint when agent_framework is missing #1503:
  • fix(core): non-finite reset guards and docstring sweep (#1447) #1514: a non-finite Retry-After or reset header now gives retry_after is None and the normal backoff. Added to "Budget headers (not breaking)". In 0.1.3, inf gave inf (capped at 30 s) and nan gave 0.0, not the NaN that fix(core): non-finite reset guards and docstring sweep (#1447) #1514's body describes. The private _check_approvals removal is omitted.
  • fix(adk): plain bridge marker and picklable Governed* classes (#1447) #1518: GovernedLiteLlm, GovernedGemini and GovernedLiteLLMClient are reachable by name on donkey_kit.integrations.adk, though not in __all__. Added to the not-breaking ADK subclasses entry.
  • chore(cli,conformance): review hygiene sweep (#1447) #1510: donkey verify exits 2 before any read when it has no gateway credential. Added as a pre-release bullet, and entry 4's exit codes now mention it.
  • fix(agent_framework): raise the install hint from policy_middleware() when the package is missing #1513 (agent_framework: policy_middleware() raises NotImplementedError instead of the install hint when agent_framework is missing #1503): the standalone policy_middleware() install-hint ImportError, folded into the ADK/LangGraph ImportError bullet. That bullet notes this one also changes 0.1.3, which raised NotImplementedError.
  • docs: ledger recount, key-header row and review wording sweep (#1447) #1495 and test(typecheck): pin the 0.2.0 headline API under mypy --strict #1491 (testing: add typecheck contracts for the new 0.2.0 headline API #1445) are docs and tests only, so they get no entry. Every PR from the review epic that changes behaviour is now covered.

Test plan

• nox -s typecheck-and-lint test-3.11 new-dependencies commit-identities docs-llms-drift: all green locally. test-3.11 runs check_doc_snippets over MIGRATION.md, and typecheck-and-lint runs check_doc_links.
• python scripts/check_doc_snippets.py ..: clean.
• Ran the claims against the installed SDK:
  • classify() on the CIBA pending/denied, Model Armor and AIDR shapes gives the new types, policy, provider and donkey.policy.type slugs;
  • the new classify.register() example registers and classifies;
  • inspect.isfunction(classify) is False;
  • derive_descriptor(mode="auto:static") raises ValueError;
  • the experimental.GovernanceCriteria warning text matches;
  • refusal_translator is still importable from both modules.
• Checked the toc anchors with a GitHub-style slugger. The 0.2.0 "New public names" title avoids a duplicate #new-exports-not-breaking anchor.
• nox (every session): not run. This PR only touches MIGRATION.md, which the site doesn't render (it links to it on GitHub), so docs-site is unaffected.
• python scripts/verify_frameworks.py: n/a, no adapter or extras change.

ADR needed?

• No: this PR changes none of those. It documents ADR 0006 and ADR 0017 outcomes, as ADR 0017 asks ("docs: add the 0.1.3 → 0.2.0 section to MIGRATION.md #1431 records it in MIGRATION.md").

Acceptance-harness impact

None.

Migration note

This PR is the migration note: MIGRATION.md's 0.2.0 section.

Post-deploy steps

None.

[tommasobolis]

Held as draft by the 0.2.0 orchestrator: entries for #1423, #1478, #1479, #1481, #1446 and #1499 are still to be added. Please do not mark ready or auto-merge.