phase 11 — detect_python_version v2 (venv-aware)

[ayhammouda]

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

Context

• Per-issue context file (read first): .planning/agent-context/detect-python-version-v2-venv-aware.md
• Pipeline: AGENT-EXECUTION-PIPELINE.md
• v1 implementation: src/mcp_server_python_docs/detection.py — detect_python_version() 3-step chain (.python-version → python3 --version → sys.version_info).
• Existing tests: tests/test_detection.py already exists (125 lines) and covers the three v1 sources. Extend it; do not recreate it.
• Tool wrapper: src/mcp_server_python_docs/server.py:372; result model: src/mcp_server_python_docs/models.py:147 (DetectPythonVersionResult).

Goal

Make detect_python_version report the Python version of the active virtual environment in the user's project, while preserving the v1 fallback chain and the existing MCP wire contract verbatim.

Acceptance criteria

• DETV2-01: When VIRTUAL_ENV is set, detection.py reads <VIRTUAL_ENV>/pyvenv.cfg, parses the version = X.Y[.Z] key (falling back to version_info if version is absent), and returns source "venv:VIRTUAL_ENV".
• DETV2-02: With no VIRTUAL_ENV, a .venv/ or venv/ directory found in cwd or an ancestor (bounded at filesystem/project root) is read via its pyvenv.cfg and returns source "venv:.venv".
• DETV2-03: uv's and poetry's project-root .venv are covered by the generic DETV2-02 check (no tool-specific branching).
• DETV2-04: The v1 fallback chain is preserved unchanged and below the new venv checks. Final order: VIRTUAL_ENV → .venv/venv dir → .python-version → python3 PATH → server runtime.
• DETV2-05: detect_python_version() still returns a (major_minor, source) tuple. Five distinct source strings exist: the two new "venv:VIRTUAL_ENV", "venv:.venv" plus the three preserved-verbatim v1 strings ".python-version file", "python3 in PATH", "server runtime".
• The source Field(description=...) in models.py (DetectPythonVersionResult, line ~147) is updated to enumerate all five sources, so the published tool schema does not lie. (Type stays str; description-only edit.)
• tests/test_detection.py is extended (not replaced): new tests cover venv:VIRTUAL_ENV and venv:.venv (incl. a Windows-layout pyvenv.cfg path), AND the existing v1 tests are hardened with monkeypatch.delenv("VIRTUAL_ENV", raising=False) so they stay deterministic now that VIRTUAL_ENV is checked first. All five source strings are covered.
• uv run pytest tests/test_detection.py -q passes.

Success criteria (illustrative)

1. Inside an activated venv (3.12) on a 3.13 host → ("3.12", "venv:VIRTUAL_ENV").
2. No venv but .python-version present → ("X.Y", ".python-version file") (v1 preserved verbatim).
3. Nothing else available → (sys-version, "server runtime") (v1 fallback preserved verbatim).

Scope boundaries

In scope: the venv-detection logic in src/mcp_server_python_docs/detection.py, the source description string in models.py, and extending tests/test_detection.py.

Out of scope (stop and comment):

• conda / mamba environments (separate phase if demand surfaces).
• Cross-platform path quirks beyond Unix + Windows.
• Changing the detect_python_version MCP wrapper signature or the (major_minor, source) return shape.
• Renaming or altering any of the three v1 source strings.

Forbidden-territory reminders (pipeline §2)

• Tool name / parameter / return shape — the server.py:372 wrapper signature and the tuple/model shape must not change. Only the set of possible source values grows, plus its description text.
• Existing tests — extend and harden, never delete or weaken. (Adding delenv to keep a test deterministic is hardening, and is required here.)
• No schema, no workflow, no pyproject.toml edits.

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
# detect_python_version backs an MCP tool — also run the wire smoke:
uv run pytest tests/test_stdio_smoke.py -q

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

• Use .github/PULL_REQUEST_TEMPLATE/agent.md; PR title matches this issue verbatim.
• This extends an existing tool's behavior (new source values) without changing its wire shape — under "Why this triggered human review", state "None" unless you find you must touch the wrapper signature, in which case stop and comment (§8).
• Ambiguity about detection order or pyvenv.cfg variants? Stop, write WORKING-NOTES.md, comment per §8 — do not invent.

Effort estimate

~2–3 hours.