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

ayhammouda · ayhammouda · commit d4d62707b309 · 2026-05-14T16:32:56.000+02:00
Per CR §9 Workstream D (decision locked 2026-05-14): formalize the
post-v0.1.5 backlog with three new MCP-tool phases. Each gets an on-disk
CONTEXT.md skeleton plus a row in .planning/ROADMAP.md. Implementation
kickoff still requires /gsd-plan-phase 0X per phase; this commit only
publishes the specs.

Phase 09 — compare_versions(symbol, v1, v2): structured per-version diff
of a stdlib symbol (signature + docstring + deprecation).

Phase 10 — whatsnew_for_version(version): the official 'What's New' page
sliced into MCP-friendly sections with kind enums and pagination.

Phase 11 — detect_python_version v2 (venv-aware): elevate the v1
detection chain to read VIRTUAL_ENV / pyvenv.cfg / .venv directories
before falling back to .python-version / python3 / sys.version_info.
Backfills tests/test_detection.py (v1 has no dedicated unit test today).

Also updates AGENTS.md 'Context Hygiene' to acknowledge .planning/ now
holds two kinds of content: live forward-looking specs (ROADMAP, phase
CONTEXTs) and archival history (pre-2026-05 content). The prior
'archival-only' framing predated the v0.1.5 launch coordination work.

GitHub issues for these three phases will be opened separately after
this PR merges (D5; not included here to avoid stale issue numbers).
diff --git a/.planning/ROADMAP.md b/.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 (PyPI debut, repo rename to `python-stdlib-mcp`, positioning lockdown, benchmark harness, launch post). See [`CHANGE-REQUEST-v0.1.5-launch.md`](../CHANGE-REQUEST-v0.1.5-launch.md) for the full scope.
+
+## 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. See the note in `.git/info/exclude` for the prior policy. With v0.1.5 the `.planning/` directory becomes a tracked, forward-facing surface for new phase CONTEXTs and roadmap entries.
diff --git a/.planning/phases/09-compare-versions/09-CONTEXT.md b/.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.11", "3.12")` returns a clear, machine-readable diff highlighting the introduction in 3.11.
+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).
diff --git a/.planning/phases/10-whatsnew/10-CONTEXT.md b/.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 accepts a Python version string. Returns `{ "sections": [{title, anchor, body, kind}] }`.
+- WNEW-02: `kind` enum: `new_module | new_feature | deprecation | removal | performance | syntax | other`.
+- WNEW-03: Token cost capped at ~2k per section; pagination supported via section index.
+
+## 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).
diff --git a/.planning/phases/11-detect-venv/11-CONTEXT.md b/.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` for `version_info`.
+- 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 where `source` discriminates `venv:VIRTUAL_ENV` / `venv:.venv` / `python-version` / `python3` / `sys.version_info`.
+
+## 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")` — v1 behavior preserved.
+3. With nothing: returns `(sys-version, "sys.version_info")` — v1 fallback preserved.
+4. Backfill: `tests/test_detection.py` covers all five `source` cases.
+5. No regression in v1 callers (`server.py` MCP tool wrapper signature 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).
diff --git a/AGENTS.md b/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/`
