phase 10 — whatsnew_for_version(version)

[ayhammouda]

Type: New MCP tool. Backlog (post-v0.1.5).
Brought up to the AGENT-EXECUTION-PIPELINE.md §3 agent-ready standard.

⚠️ This issue adds a 7th public tool — human-review-required

A new tool name + parameters + return shape is public API surface — pipeline §2 forbidden territory and a §7 human-review trigger. This is allowed work, but the agent must: open the PR with the 🛑 needs-human-review label, not request auto-merge, fill the "Why this triggered human review" section, and leave the existing six tools' names/parameters/return shapes untouched.

Context

• Per-issue context file (read first): .planning/agent-context/whatsnew-for-version.md
• Pipeline: AGENT-EXECUTION-PIPELINE.md
• Touch-points: ingestion already walks every .fjson (ingestion/sphinx_json.py, rglob("*.fjson")), so whatsnew/* is already in the index as documents+sections; version validation/error reuse via services/version_resolution.py:13 (validate_version); pagination/truncation via retrieval/budget.py (apply_budget); result models in models.py; tool registration in server.py (after compare_versions).

Goal

Add a whatsnew_for_version MCP tool that returns the official "What's New in Python X.Y" content as structured, topic-scoped, paginated sections sourced only from the already-ingested index (no runtime network).

Acceptance criteria

• WNEW-01: Tool signature whatsnew_for_version(version: str, kind: str | None = None, start_index: int = 0, max_sections: int = 20) returns {"sections": [{title, anchor, body, kind}], "next_start_index": int | None} via a new pydantic result model in models.py.
• WNEW-02: kind ∈ new_module | new_feature | deprecation | removal | performance | syntax | other, modeled as a Literal[...]; kind filters to a single value; classification is derived from already-ingested section title/anchor signals (offline), defaulting to other.
• WNEW-03: Each section body is capped at ~2k tokens (approximate via apply_budget's char budget — do not add a tokenizer dependency); over-cap sections truncate with a clear marker + a get_docs hint; start_index/next_start_index round-trip correctly.
• whatsnew_for_version("3.12") returns ≥10 sections, each with a non-empty body and a stable anchor (the sections.anchor already in the index).
• Filtering works: whatsnew_for_version("3.12", kind="deprecation") returns only deprecation sections.
• A missing/unindexed version raises the same actionable error as compare_versions — i.e. reuse validate_version, which names the available versions.
• tests/test_whatsnew.py covers two representative versions, the kind filter, a pagination round-trip, and the missing-version error, bootstrapping an index the way tests/test_compare_versions.py does (no live CPython build).
• The canonical gate plus the wire + corpus gates below pass.

Scope boundaries

In scope: a new query service (e.g. services/whatsnew.py) wired into AppContext, new result model(s) in models.py, the new tool wrapper in server.py, and tests/test_whatsnew.py.

Out of scope (stop and comment):

• Any change to ingestion, schema.sql, or the existing six tools — whatsnew/* is already ingested; this is a query-only addition. If whatsnew sections are unexpectedly absent from the index, stop and comment (do not add ingestion).
• Fetching docs.python.org at runtime (violates offline-first principle 2.2).
• Third-party "what's new" guides; cross-version aggregation (use compare_versions).
• Adding any runtime dependency (e.g. a tokenizer).

Forbidden-territory reminders (pipeline §2 / §7)

• New public tool = API surface → 🛑 needs-human-review, no auto-merge, disclosure section filled.
• schema.sql / migrations — off-limits.
• pyproject.toml [project] / new runtime deps — off-limits; reuse budget.py.
• Existing tests and the six existing tools — do not modify.

Validation commands (pipeline §5)

uv run ruff check src/ tests/
uv run pyright src/
uv run pytest --tb=short -q
uv run python-docs-mcp-server doctor
# new tool touches the MCP wire protocol + queries the corpus:
uv run pytest tests/test_stdio_smoke.py -q
uv run python-docs-mcp-server validate-corpus

PR template & recovery (pipeline §6, §8)

• Use .github/PULL_REQUEST_TEMPLATE/agent.md; PR title matches this issue verbatim; Closes #33.
• Under "Why this triggered human review", disclose the new public tool (API surface) and confirm the existing six tools are unchanged.
• This is realistically a multi-file task (~4–6h). If it exceeds 2× that, or the acceptance criteria turn out ambiguous, stop, write WORKING-NOTES.md, and comment per §8 — no scope expansion.

Effort estimate

~4–6 hours. (Larger than a first-run confidence task — flagged as the riskier of the two backlog conversions because it adds public API surface.)