From d4d62707b309847de0e5649e96ebdba882a0dff9 Mon Sep 17 00:00:00 2001 From: Aymen Hammouda Date: Thu, 14 May 2026 16:32:56 +0200 Subject: [PATCH 1/3] feat(planning): scaffold phases 9/10/11 backlog + forward-facing .planning/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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). --- .planning/ROADMAP.md | 20 +++++++++ .../phases/09-compare-versions/09-CONTEXT.md | 40 +++++++++++++++++ .planning/phases/10-whatsnew/10-CONTEXT.md | 40 +++++++++++++++++ .planning/phases/11-detect-venv/11-CONTEXT.md | 43 +++++++++++++++++++ AGENTS.md | 24 +++++------ 5 files changed, 155 insertions(+), 12 deletions(-) create mode 100644 .planning/ROADMAP.md create mode 100644 .planning/phases/09-compare-versions/09-CONTEXT.md create mode 100644 .planning/phases/10-whatsnew/10-CONTEXT.md create mode 100644 .planning/phases/11-detect-venv/11-CONTEXT.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..a5f6f7b --- /dev/null +++ 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 new file mode 100644 index 0000000..06196ad --- /dev/null +++ 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 new file mode 100644 index 0000000..ebc2951 --- /dev/null +++ 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 ``" 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/.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 new file mode 100644 index 0000000..6ea9bd0 --- /dev/null +++ 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 index 6cb220b..931782c 100644 --- 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/` From 786ab1645455779d4a5d9e659b5dd94a3342c0bf Mon Sep 17 00:00:00 2001 From: Aymen Hammouda Date: Thu, 14 May 2026 16:37:59 +0200 Subject: [PATCH 2/3] docs(planning): fix CONTEXT spec inaccuracies surfaced by code review Three fixes from the post-merge spec audit on PR #27: 1. Phase 11 source discriminators: align with the actual v1 strings in src/mcp_server_python_docs/detection.py. v1 returns '.python-version file' / 'python3 in PATH' / 'server runtime' (not the simplified labels the original CONTEXT spec used). v2 preserves these verbatim below the new venv:* sources. 2. Phase 09 success criterion 1: use compare_versions('asyncio.TaskGroup', '3.10', '3.11') instead of '3.11'-'3.12' for the introduction example. The symbol was introduced in 3.11, so a 3.10->3.11 diff is the right surface to test 'newly introduced' detection. A 3.11->3.12 diff would show no change for TaskGroup and could pass vacuously. 3. ROADMAP.md Historical section: drop the misleading reference to '.git/info/exclude'. That file is local-only and contains gitignore syntax, not a policy narrative; readers checking it would not find the explanation. Rephrased to be self-contained. --- .planning/ROADMAP.md | 2 +- .planning/phases/09-compare-versions/09-CONTEXT.md | 2 +- .planning/phases/11-detect-venv/11-CONTEXT.md | 10 +++++----- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index a5f6f7b..6b6e88f 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -17,4 +17,4 @@ These are planned, not committed. Phase CONTEXTs at [`phases/09-compare-versions ## 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. +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. diff --git a/.planning/phases/09-compare-versions/09-CONTEXT.md b/.planning/phases/09-compare-versions/09-CONTEXT.md index 06196ad..5c27ef6 100644 --- a/.planning/phases/09-compare-versions/09-CONTEXT.md +++ b/.planning/phases/09-compare-versions/09-CONTEXT.md @@ -20,7 +20,7 @@ Add an MCP tool `compare_versions(symbol, v1, v2)` that returns a structured dif ## Success criteria -1. `compare_versions("asyncio.TaskGroup", "3.11", "3.12")` returns a clear, machine-readable diff highlighting the introduction in 3.11. +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). diff --git a/.planning/phases/11-detect-venv/11-CONTEXT.md b/.planning/phases/11-detect-venv/11-CONTEXT.md index 6ea9bd0..64fca4a 100644 --- a/.planning/phases/11-detect-venv/11-CONTEXT.md +++ b/.planning/phases/11-detect-venv/11-CONTEXT.md @@ -19,15 +19,15 @@ Make `detect_python_version` venv-aware: report the Python version of the *activ - 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`. +- 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")` — 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). +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 From 2b0d2ca9667bb39a6c425a47791249197cb3aaa6 Mon Sep 17 00:00:00 2001 From: Aymen Hammouda Date: Thu, 14 May 2026 17:48:00 +0200 Subject: [PATCH 3/3] docs(planning): codex review fixes for PR #4 phase specs Three findings from a second codex:review pass on PR #27: 1. ROADMAP.md inline-summary v0.1.5 scope instead of linking to ../CHANGE-REQUEST-v0.1.5-launch.md. The CR document is intentionally untracked (it's a working planning artifact), so the link was dead from a fresh checkout's perspective. Replaced with a one-sentence summary of the five workstreams. 2. Phase 10 WNEW-01: define the kind filter and pagination params that the success criteria already exercise. Previous WNEW-01 listed only the version input, making the spec internally inconsistent with success criterion 3 (kind="deprecation") and WNEW-03 (pagination). 3. Phase 11 DETV2-01: parse the standard `version = X.Y[.Z]` key in pyvenv.cfg (written by python -m venv). version_info is the optional fallback, not the primary key as previously specified. Confirmed against the local .venv/pyvenv.cfg in the workspace. --- .planning/ROADMAP.md | 2 +- .planning/phases/10-whatsnew/10-CONTEXT.md | 4 ++-- .planning/phases/11-detect-venv/11-CONTEXT.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 6b6e88f..416d11c 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -3,7 +3,7 @@ ## 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. +- **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) diff --git a/.planning/phases/10-whatsnew/10-CONTEXT.md b/.planning/phases/10-whatsnew/10-CONTEXT.md index ebc2951..97429f6 100644 --- a/.planning/phases/10-whatsnew/10-CONTEXT.md +++ b/.planning/phases/10-whatsnew/10-CONTEXT.md @@ -14,9 +14,9 @@ Return the official "What's New in Python ``" content as structured sec ## Requirements -- WNEW-01: Tool accepts a Python version string. Returns `{ "sections": [{title, anchor, body, kind}] }`. +- 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: Token cost capped at ~2k per section; pagination supported via section index. +- 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 diff --git a/.planning/phases/11-detect-venv/11-CONTEXT.md b/.planning/phases/11-detect-venv/11-CONTEXT.md index 64fca4a..2b5291d 100644 --- a/.planning/phases/11-detect-venv/11-CONTEXT.md +++ b/.planning/phases/11-detect-venv/11-CONTEXT.md @@ -15,7 +15,7 @@ Make `detect_python_version` venv-aware: report the Python version of the *activ ## Requirements -- DETV2-01: Detect active venv via the `VIRTUAL_ENV` env var; if present, read `$VIRTUAL_ENV/pyvenv.cfg` for `version_info`. +- 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.