feat(planning): scaffold phases 9/10/11 backlog + forward-facing .planning/

.planning/ROADMAP.md

@@ -0,0 +1,20 @@
+# Roadmap
+
+## Current
+
+- **v0.1.4** — shipped (pre-PyPI; installed via `uvx --from git+…`)
+- **v0.1.5** — in progress. Five coordinated workstreams: positioning lockdown ("canonical Python stdlib oracle for AI coding agents — always free, always MIT, token-frugal"); first PyPI publish via Trusted Publishing; GitHub repo rename to `python-stdlib-mcp` (PyPI package name stays `python-docs-mcp-server`); benchmark harness against competing docs MCPs; coordinated launch post on a personal blog, dev.to, and Show HN.
+
+## Backlog (post-v0.1.5)
+
+| Phase | Title | Tool surface | Issue |
+|-------|-------|--------------|-------|
+| 09 | `compare_versions(symbol, v1, v2)` | New MCP tool | #TBD-link-after-PR-merges |
+| 10 | `whatsnew_for_version(version)` | New MCP tool | #TBD-link-after-PR-merges |
+| 11 | `detect_python_version` v2 (venv-aware) | Existing tool enhancement | #TBD-link-after-PR-merges |
+
+These are planned, not committed. Phase CONTEXTs at [`phases/09-compare-versions/`](phases/09-compare-versions/09-CONTEXT.md), [`phases/10-whatsnew/`](phases/10-whatsnew/10-CONTEXT.md), [`phases/11-detect-venv/`](phases/11-detect-venv/11-CONTEXT.md). Implementation kickoff requires `/gsd-plan-phase 0X`.
+
+## Historical
+
+Pre-2026-05-14 GSD workflow artifacts (phases 1–8 for v0.1.0) live in maintainers' local worktrees and are intentionally not tracked in this repo — they remain accessible to those who ran the original GSD workflow locally but are not load-bearing for current implementation work. With v0.1.5 the `.planning/` directory becomes a tracked, forward-facing surface for new phase CONTEXTs and roadmap entries.

.planning/phases/09-compare-versions/09-CONTEXT.md

@@ -0,0 +1,40 @@
+# Phase 09 — compare_versions(symbol, v1, v2)
+
+**Status:** Backlog (post-v0.1.5)
+**Type:** New MCP tool
+
+## Goal
+
+Add an MCP tool `compare_versions(symbol, v1, v2)` that returns a structured diff of a stdlib symbol's signature, behavior, and docstring between two Python versions.
+
+## Depends on
+
+- v0.1.5 ships (PyPI debut + repo rename complete).
+- Index supports the two versions being compared (handled by `build-index`).
+
+## Requirements
+
+- CMPR-01: Tool accepts `(symbol: str, v1: str, v2: str)`. Returns a structured diff: signature change, docstring delta, deprecation flag, see-also additions/removals.
+- CMPR-02: Both versions must already be indexed; if not, tool returns an actionable error pointing at `build-index`.
+- CMPR-03: Diff format is JSON-serializable and token-frugal — no full re-printing of unchanged paragraphs.
+
+## Success criteria
+
+1. `compare_versions("asyncio.TaskGroup", "3.10", "3.11")` returns a clear, machine-readable diff showing the symbol was newly introduced in 3.11 (e.g. an `added` or `new_in` marker, not just a delta of existing fields).
+2. Comparing identical versions returns an empty diff with an explicit "no change" marker.
+3. Missing-version cases return an actionable error with the indexed-version list.
+4. Token cost of a typical diff is under 300 tokens (vs ~1500 for fetching both full doc pages).
+5. Integration test in `tests/test_compare_versions.py` exercises 3 representative symbols (one changed, one unchanged, one missing).
+
+## Plans
+
+TBD — run `/gsd-plan-phase 09` after this issue is prioritized.
+
+## UI hint
+
+No UI surface; pure MCP tool.
+
+## Out of scope
+
+- Cross-language diffs (Python stdlib only).
+- Non-symbol diffs (module-level changes belong in phase 10).

.planning/phases/10-whatsnew/10-CONTEXT.md

@@ -0,0 +1,40 @@
+# Phase 10 — whatsnew_for_version(version)
+
+**Status:** Backlog (post-v0.1.5)
+**Type:** New MCP tool
+
+## Goal
+
+Return the official "What's New in Python `<version>`" content as structured sections, scoped by topic — new modules, deprecations, removals, performance, syntax. The current alternative is for the agent to fetch a full HTML page; this tool returns just the requested sections.
+
+## Depends on
+
+- v0.1.5 ships.
+- Ingestion already covers `whatsnew/<version>.html` (verify during phase planning).
+
+## Requirements
+
+- WNEW-01: Tool signature: `whatsnew_for_version(version: str, kind: str | None = None, start_index: int = 0, max_sections: int = 20)`. `kind` filters to a single `kind` value (see WNEW-02); `start_index` + `max_sections` paginate the response. Returns `{ "sections": [{title, anchor, body, kind}], "next_start_index": int | None }`.
+- WNEW-02: `kind` enum: `new_module | new_feature | deprecation | removal | performance | syntax | other`.
+- WNEW-03: Each section's `body` is capped at ~2k tokens. If a single section exceeds the cap, truncate with a clear marker and a `get_docs` hint. Pagination via `start_index` / `next_start_index` round-trips.
+
+## Success criteria
+
+1. `whatsnew_for_version("3.12")` returns ≥10 sections, each with a non-empty body.
+2. Each section has a stable anchor matching docs.python.org.
+3. Filtering by `kind` is supported (`whatsnew_for_version("3.12", kind="deprecation")`).
+4. Missing version returns the same actionable error pattern as `compare_versions`.
+5. Integration test in `tests/test_whatsnew.py` covers two representative versions.
+
+## Plans
+
+TBD.
+
+## UI hint
+
+No UI surface; pure MCP tool.
+
+## Out of scope
+
+- Third-party "what's new" guides.
+- Cross-version aggregation (use `compare_versions` instead).

.planning/phases/11-detect-venv/11-CONTEXT.md

@@ -0,0 +1,43 @@
+# Phase 11 — detect_python_version v2 (venv-aware)
+
+**Status:** Backlog (post-v0.1.5)
+**Type:** Enhancement of existing MCP tool
+
+## Goal
+
+Make `detect_python_version` venv-aware: report the Python version of the *active virtual environment* in the user's project, not just the value from `.python-version` or `python3 --version` on PATH.
+
+## Depends on
+
+- v0.1.5 ships.
+- v1 implementation at `src/mcp_server_python_docs/detection.py` (current 3-step detection order: `.python-version` → `python3 --version` → `sys.version_info`).
+- v1 has NO dedicated unit test file — backfill `tests/test_detection.py` as part of this phase.
+
+## Requirements
+
+- DETV2-01: Detect active venv via the `VIRTUAL_ENV` env var; if present, read `$VIRTUAL_ENV/pyvenv.cfg` and parse the `version = X.Y[.Z]` key (the standard key written by `python -m venv`). Fall back to `version_info` only if `version` is absent — some tools write that variant.
+- DETV2-02: Detect `.venv/` or `venv/` directories in cwd or its ancestors (up to project root).
+- DETV2-03: Detect `uv`'s `.venv` and `poetry`'s `.venv` patterns.
+- DETV2-04: Preserve v1 fallback chain unchanged below the new venv checks.
+- DETV2-05: Return `(major_minor, source)` tuple. **New v2 sources:** `"venv:VIRTUAL_ENV"`, `"venv:.venv"`. **Existing v1 sources (preserved unchanged, see `src/mcp_server_python_docs/detection.py`):** `".python-version file"`, `"python3 in PATH"`, `"server runtime"`. Total: 5 distinct source strings.
+
+## Success criteria
+
+1. Inside an activated venv (3.12) on a 3.13 host: returns `("3.12", "venv:VIRTUAL_ENV")`.
+2. With no venv but `.python-version` present: returns `("X.Y", ".python-version file")` — v1 behavior preserved verbatim.
+3. With nothing else available: returns `(sys-version, "server runtime")` — v1 fallback preserved verbatim.
+4. Backfill: `tests/test_detection.py` covers all five `source` cases (2 new + 3 preserved).
+5. No regression in v1 callers (`server.py` MCP tool wrapper signature unchanged; existing source strings unchanged).
+
+## Plans
+
+TBD.
+
+## UI hint
+
+No UI surface; pure MCP tool.
+
+## Out of scope
+
+- conda / mamba environments (separate phase if demand surfaces).
+- Cross-platform venv path quirks beyond Unix + Windows (both must be tested).

AGENTS.md

@@ -83,15 +83,15 @@ Before calling work complete:
 
 ## Context Hygiene
 
-Treat `.planning/` as archival project history, not live repo truth.
-
-Start with these files instead:
-
-- `README.md`
-- `CONTRIBUTING.md`
-- `.github/INTEGRATION-TEST.md`
-- `tests/`
-
-The generated planning files may still be useful for maintainers who want the
-old GSD workflow context, but they should not drive routine implementation
-decisions.
+`.planning/` mixes archival history with forward-facing phase CONTEXTs.
+
+- `.planning/ROADMAP.md` and `.planning/phases/0X-…/0X-CONTEXT.md` are live,
+  forward-looking specs — read these first when starting a new phase.
+- Anything else in `.planning/` (especially content dated 2026-04 or earlier)
+  is archival history. It may help maintainers reconstruct prior context but
+  should not drive routine implementation decisions.
+- For the source of truth about *what the code does today*, start with:
+  - `README.md`
+  - `CONTRIBUTING.md`
+  - `.github/INTEGRATION-TEST.md`
+  - `tests/`