python-docs-mcp-server 0.1.5__tar.gz → 0.2.0__tar.gz

{python_docs_mcp_server-0.1.5 → python_docs_mcp_server-0.2.0}/.github/INTEGRATION-TEST.md

@@ -38,8 +38,10 @@ npx @modelcontextprotocol/inspector uv --directory . run python-docs-mcp-server
 - [ ] Confirm the tool list includes:
   - `search_docs`
   - `get_docs`
+  - `lookup_package_docs`
   - `list_versions`
   - `detect_python_version`
+  - `compare_versions`
 - [ ] Call `search_docs` with query `asyncio.TaskGroup`, `kind="symbol"`, `version="3.13"`
   - Expected: exact symbol hit with `library/asyncio-task.html`
 - [ ] Call `get_docs` for the returned slug and anchor
@@ -48,6 +50,8 @@ npx @modelcontextprotocol/inspector uv --directory . run python-docs-mcp-server
   - Expected: indexed versions appear with the configured default version
 - [ ] Call `detect_python_version`
   - Expected: returns local interpreter information without breaking the session
+- [ ] Call `compare_versions` with `symbol="asyncio.TaskGroup"`, `v1="3.10"`, `v2="3.11"`
+  - Expected: result with `change="added"` and `new_in="3.11"`, JSON serialization under ~1200 bytes
 - [ ] Observe no protocol corruption or unexplained disconnects in Inspector
 
 ## Test 2: Claude Desktop integration

python_docs_mcp_server-0.2.0/.github/RELEASE.md

@@ -0,0 +1,114 @@
+# Release Process
+
+## One-Time Setup: PyPI Trusted Publishing
+
+Already configured for this project — these steps are kept for reference when forking or recovering the publisher state.
+
+1. Go to https://pypi.org/manage/account/publishing/
+2. Add a publisher (pending or active):
+   - **PyPI project name**: `python-docs-mcp-server`
+   - **Owner**: your GitHub username or org (this repo: `ayhammouda`)
+   - **Repository**: `python-docs-mcp-server`
+   - **Workflow name**: `release.yml`
+   - **Environment name**: `pypi`
+3. In the GitHub repo, go to Settings > Environments
+4. Create an environment named `pypi`
+5. (Optional) Add environment protection rules:
+   - Required reviewers (recommended)
+   - Deployment branches: only `main` tags
+
+## Coverage notes
+
+**Runtime coverage:** the release workflow builds and tests against Python 3.13 only. Python 3.12 is covered by the CI workflow (`ci.yml`), which runs a 2×2 matrix (3.12/3.13 × ubuntu/macos) on every push to `main`. Since tags are created from commits that have already passed CI, 3.12 compatibility is verified before the release workflow runs. This is an accepted trade-off to keep the release artifact pipeline simple (single Python version produces the wheel).
+
+**Documentation coverage:** the full docs index target is Python documentation versions 3.10 through 3.14.
+
+---
+
+## Release Checklist
+
+Replace `X.Y.Z` below with the version you are releasing (e.g. `0.1.7`). Complete each step in order; do not skip ahead. The release workflow at `.github/workflows/release.yml` runs four jobs in sequence on every `v*` tag push: `build` → `publish` (PyPI) → `publish-mcp-registry` → `github-release`.
+
+### Pre-Release Verification
+
+- [ ] All CI tests green on `main`: https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/ci.yml
+- [ ] Local test suite passes:
+  ```bash
+  uv run pytest --tb=short -q
+  uv run ruff check src/ tests/
+  uv run pyright src/
+  ```
+- [ ] All four version-bearing files agree on `X.Y.Z` (the release workflow's `Verify tag matches package version` step enforces this; matching here saves a CI round-trip):
+  ```bash
+  grep '^version' pyproject.toml
+  python3 -c 'import json; d = json.load(open("server.json")); print("server.json:", d["version"], "/ packages[0]:", d["packages"][0]["version"])'
+  grep '^name = "python-docs-mcp-server"' -A1 uv.lock | head -2
+  ```
+- [ ] `server.json` validates against the live MCP Registry schema. MCP Registry enforces stricter limits than PyPI (e.g. `description ≤ 100 chars`); validating before the tag prevents a half-published release (PyPI succeeds while MCP Registry rejects, as happened on v0.1.5 → recovered in v0.1.6):
+  ```bash
+  curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+  ./mcp-publisher validate server.json
+  ```
+  Must report `✅ server.json is valid`. If validation fails, shorten `server.json` `description` on `main` before tagging (the `pyproject.toml` description is unbounded by this constraint and can stay longer).
+- [ ] Integration tests from `.github/INTEGRATION-TEST.md` are complete and signed off
+- [ ] `Doctor` subcommand passes:
+  ```bash
+  uv run python-docs-mcp-server doctor
+  ```
+- [ ] `CHANGELOG.md` has a dated entry for `[X.Y.Z]`
+
+### Tag and Release
+
+- [ ] Create the annotated tag (replace `X.Y.Z` everywhere):
+  ```bash
+  git tag -a vX.Y.Z -m "Release vX.Y.Z
+
+  <one-line summary of what shipped>
+
+  See CHANGELOG.md for the full entry."
+  ```
+- [ ] Push the tag to trigger the release workflow:
+  ```bash
+  git push origin vX.Y.Z
+  ```
+- [ ] Watch the workflow run to completion:
+  ```bash
+  gh run watch $(gh run list --workflow=release.yml --limit 1 --json databaseId -q '.[0].databaseId') --exit-status
+  ```
+- [ ] All four jobs green: `build` → `publish` → `publish-mcp-registry` → `github-release`
+
+### Post-Release Verification
+
+- [ ] PyPI listing exists with attestation badge: `https://pypi.org/project/python-docs-mcp-server/X.Y.Z/`
+- [ ] Fresh install test from a clean shell (cache-busted so the new version actually resolves):
+  ```bash
+  uv cache clean python-docs-mcp-server 2>/dev/null || true
+  uvx --refresh python-docs-mcp-server@X.Y.Z --version
+  # Expected: python-docs-mcp-server X.Y.Z
+  ```
+- [ ] Full install flow:
+  ```bash
+  uvx python-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14
+  uvx python-docs-mcp-server doctor
+  ```
+  Both must complete successfully.
+- [ ] MCP Registry shows `X.Y.Z` as the `isLatest` entry:
+  ```bash
+  curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=python-docs-mcp-server' | \
+    python3 -c "import json,sys; d=json.load(sys.stdin); print(next((e['server']['version'] for e in d['servers'] if e['_meta']['io.modelcontextprotocol.registry/official']['isLatest']), 'no latest'))"
+  ```
+- [ ] GitHub Release exists at `https://github.com/ayhammouda/python-docs-mcp-server/releases/tag/vX.Y.Z` with wheel + sdist attached and auto-generated notes
+- [ ] **Slow E2E workflow** passes (manually triggered after publish):
+  - Run GitHub Actions workflow `Slow E2E` (`.github/workflows/e2e.yml`)
+  - Python 3.13 and 3.14 jobs both pass
+  - Each job installs the built wheel and runs `build-index --versions 3.10,3.11,3.12,3.13,3.14`, `doctor`, and `validate-corpus`
+- [ ] Claude Desktop manual smoke test:
+  Configure `mcpServers` with `uvx python-docs-mcp-server` and verify a known query (e.g. "what is asyncio.TaskGroup") returns a correct hit.
+
+### Release Complete
+
+- [ ] All four `release.yml` jobs green for `vX.Y.Z`
+- [ ] PyPI page shows `X.Y.Z` with the "Provenance" attestation badge
+- [ ] MCP Registry `isLatest` entry points at `X.Y.Z`
+- [ ] GitHub Release `vX.Y.Z` exists with both dist artifacts attached
+- [ ] `CHANGELOG.md` `[X.Y.Z]` entry is committed on `main`

python_docs_mcp_server-0.2.0/.github/TEST-STRATEGY.md

@@ -0,0 +1,101 @@
+# Test Strategy
+
+Canonical map of **what we test, at which layer, and where the gaps are**.
+Pairs with the how-to-run instructions in `CONTRIBUTING.md` and the manual
+client runbook in `.github/INTEGRATION-TEST.md`.
+
+Last verified: 2026-05-29 — 284 tests passing, ruff clean, pyright 0 errors.
+
+## 1. The pyramid (current shape)
+
+```
+        /  stdio E2E   \      9 tests   — real MCP process over stdio
+       /  integration   \    ~38 tests  — multi-version, publish, cache, phase1
+      /   unit / service  \  ~230 tests — services, retrieval, ingestion, compare
+     /  contract + regression \  38 tests — schema snapshots, stability, curated cases
+```
+
+This is the right shape: a wide, fast base and a thin, slow top. Keep new
+tests pushed **down** the pyramid — only add an stdio E2E test when a bug can
+*only* manifest across the process boundary (framing, lifespan DI, stdout
+hygiene).
+
+## 2. Expected features → coverage map
+
+The server exposes **6 MCP tools**. Every tool must have at least one
+behavioral test and appear in the schema snapshot.
+
+| Tool / feature         | Primary tests                                                        | Layer            | Status |
+|------------------------|----------------------------------------------------------------------|------------------|--------|
+| `search_docs`          | `test_services`, `test_retrieval`, `test_synonyms`, `test_stability` | unit + regression| STRONG |
+| `get_docs`             | `test_services`, `test_retrieval`, `test_persistent_docs_cache`, `test_mcp_get_docs_cache_smoke` | unit + integration | STRONG |
+| `list_versions`        | `test_services`, `test_multi_version`                                | unit + integration| GOOD   |
+| `compare_versions`     | `test_compare_versions` (15), `test_services`                        | unit             | GOOD   |
+| `lookup_package_docs`  | `test_package_docs` (8)                                              | unit only        | THIN   |
+| `detect_python_version`| `test_detection` (12)                                               | unit             | GOOD   |
+
+Cross-cutting coverage:
+
+- **Schema contract**: `test_schema.py`, `test_schema_snapshot.py` — input/output
+  JSON schemas for each tool are frozen as fixtures; a wire-shape change fails CI.
+- **Multi-version routing**: `test_multi_version.py` — version param resolution and
+  default fallback across indexed doc sets.
+- **Regression**: `test_retrieval_regression.py` (curated query→expected cases) and
+  `test_stability.py` (property-based invariants that survive CPython doc revisions).
+- **Process hygiene**: `test_stdio_smoke.py`, `test_stdio_hygiene.py` — confirm a real
+  stdio server starts, answers, and keeps stdout free of non-protocol noise.
+- **Packaging / CI**: `test_packaging.py`, `test_ci_workflows.py` — installable
+  artifact + workflow file invariants.
+
+## 3. What to test, by component type
+
+- **Services** (`services/`): business logic in isolation against a `tmp_path`
+  SQLite fixture. Cover the happy path, every error branch (`DocsServerError`
+  subclasses), and token-budget trimming.
+- **Retrieval/ranking** (`retrieval/`): query parsing, FTS5 behavior, ranker
+  ordering. Use property assertions (`>= 1 result`, substring match) over exact
+  content so upstream doc edits don't break the suite.
+- **Ingestion** (`ingestion/`): parse valid + deliberately broken `.fjson`
+  fixtures; assert idempotency on re-publish.
+- **Server layer** (`server.py`): thin — it only delegates to services and maps
+  `DocsServerError → ToolError`. Cover that mapping via stdio smoke, not unit tests.
+- **Detection** (`detection.py`): pure environment probing — see gap below.
+
+## 4. Coverage targets
+
+No line-coverage gate is enforced (no `pytest-cov` in the dev deps). The bar is
+**behavioral**, not numeric:
+
+- Every public tool has ≥1 happy-path + ≥1 error-path test.
+- Every `errors.py` exception type is raised by at least one test.
+- Every wire-facing model is pinned by a schema snapshot.
+
+Adopt these as the definition of done for new tools. A line-coverage gate is
+optional future work; if added, target the `services/` and `retrieval/`
+packages, not `server.py` (intentionally thin) or `__main__.py`.
+
+## 5. Known gaps
+
+1. **`detection.py` — CLOSED (2026-05-29).** `tests/test_detection.py` now
+   covers all three branches of the fallback chain (`.python-version` file →
+   `python3` in PATH → `sys.version_info`), `_parse_major_minor` parsing, and
+   `match_to_indexed` — 12 tests. The isolation pattern (`monkeypatch.chdir` to
+   escape a real `.python-version`, `monkeypatch.setattr` on `subprocess.run`)
+   is the reference for testing order-dependent environment probing.
+2. **`lookup_package_docs` has no stdio smoke (LOW).** Covered at the service
+   layer only; the PyPI-allowlist trust boundary is never exercised end-to-end.
+3. **No negative version-resolution E2E (LOW).** Unknown-version errors are
+   unit-tested but not asserted over the stdio boundary.
+
+## 6. Reference cases — `detection.py` (now implemented in `test_detection.py`)
+
+| Case                                   | Expectation                              |
+|----------------------------------------|------------------------------------------|
+| `.python-version` file present in cwd  | returns `(version, ".python-version file")` |
+| `.python-version` malformed / empty    | falls through to next source, no crash   |
+| no file, `python3` on PATH             | returns `(version, "python3 in PATH")`   |
+| no file, no `python3`                  | returns runtime `(X.Y, "server runtime")`|
+| `_parse_major_minor("Python 3.13.2")`  | `"3.13"`                                  |
+| `_parse_major_minor("no digits here")` | `None`                                    |
+| `match_to_indexed("3.13", ["3.13"])`   | `"3.13"`                                  |
+| `match_to_indexed("3.9", ["3.13"])`    | `None`                                    |

python_docs_mcp_server-0.2.0/.planning/ROADMAP.md

@@ -0,0 +1,23 @@
+# Roadmap
+
+## Shipped
+
+- **v0.1.4** — pre-PyPI; installed via `uvx --from git+…`.
+- **v0.1.5** — first PyPI release. Outcomes: positioning lockdown ("canonical Python stdlib oracle for AI coding agents — always free, always MIT, token-frugal"); PyPI publish via Trusted Publishing; benchmark harness against competing docs MCPs; coordinated launch post (personal blog, dev.to, Show HN). The GitHub repo rename to `python-stdlib-mcp` was dropped on 2026-05-14 — the repo and PyPI package keep the `python-docs-mcp-server` name.
+- **v0.1.6** — MCP Registry hotfix: trimmed `server.json` description to ≤100 chars ([#30](https://github.com/ayhammouda/python-docs-mcp-server/pull/30)) so the package validates against the MCP Registry schema. Follow-up: RELEASE.md generalized to be version-agnostic ([#35](https://github.com/ayhammouda/python-docs-mcp-server/pull/35), [#36](https://github.com/ayhammouda/python-docs-mcp-server/pull/36)) so the next release follows the documented flow without one-time scaffolding.
+
+## Backlog (post-v0.1.6)
+
+Triaged 2026-05-26 — all three phases remain in scope. Phase 10 is up next.
+
+| Phase | Title | Tool surface | Issue | Status |
+|-------|-------|--------------|-------|--------|
+| 09 | `compare_versions(symbol, v1, v2)` | New MCP tool | [#32](https://github.com/ayhammouda/python-docs-mcp-server/issues/32) | **✓ Complete** — 5/5 plans, verified 2026-05-29 |
+| 10 | `whatsnew_for_version(version)` | New MCP tool | [#33](https://github.com/ayhammouda/python-docs-mcp-server/issues/33) | Backlog |
+| 11 | `detect_python_version` v2 (venv-aware) | Existing tool enhancement | [#34](https://github.com/ayhammouda/python-docs-mcp-server/issues/34) | Backlog |
+
+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: `/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 became a tracked, forward-facing surface for new phase CONTEXTs and roadmap entries.

python_docs_mcp_server-0.2.0/.planning/phases/09-compare-versions/09-01-data-shape-spike-PLAN.md

@@ -0,0 +1,205 @@
+---
+phase: 09-compare-versions
+plan: 01
+type: execute
+wave: 0
+depends_on: []
+files_modified:
+  - .planning/phases/09-compare-versions/09-01-data-shape-spike-SUMMARY.md
+autonomous: true
+requirements:
+  - CMPR-01
+must_haves:
+  truths:
+    - "A reproducible in-memory two-version SQLite fixture (built from the same `bootstrap_schema` + `doc_sets`/`documents`/`sections`/`symbols` insert pattern used by `tests/test_multi_version.py::multi_version_db`) is the source of all probe data — NOT the user's `index.db` cache, which is mutable and environment-dependent."
+    - "The fixture seeds three known Sphinx-version-directive prose forms verbatim: `\"New in version 3.11.\"` for asyncio.TaskGroup in 3.11, `\"Changed in version 3.10:\"` for asyncio.run in 3.11, and `\"Deprecated since version 3.12.\"` for at least one symbol. This converts A1 / A2 from \"verify against live data\" into \"document the prose forms RESEARCH §Q3/Q4 already specifies\" — the spike's job is to lock the regex strings, not rediscover them."
+    - "If the executor wants to additionally probe a live `index.db` (where one happens to exist), that is documented under `## Optional live-index cross-check` in the SUMMARY but is NEVER required for the spike to be considered complete."
+    - "The regex patterns to extract `new_in` / `changed_in` / `deprecated_in` from `sections.content_text` are pinned to verified prose forms with explicit fallback decisions (return None) recorded for each extractor."
+  artifacts:
+    - path: ".planning/phases/09-compare-versions/09-01-data-shape-spike-SUMMARY.md"
+      provides: "Locked regex pattern strings + fallback policy for CompareService extractors, sourced from a reproducible fixture, not user-cache state."
+      contains: "## Locked regex patterns"
+  key_links:
+    - from: "09-01-data-shape-spike-SUMMARY.md"
+      to: "services/compare.py (Plan 03)"
+      via: "regex pattern strings recorded under '## Locked regex patterns'"
+      pattern: "Locked regex patterns"
+---
+
+<objective>
+Lock the regex patterns that `CompareService.compare` will use to extract `new_in` / `changed_in` / `deprecated_in` / `see_also` from section markdown, using a reproducible test fixture as the data source — NOT the user's mutable `index.db` cache.
+
+Purpose: Plan 03 needs four concrete regex strings (or explicit `None`-fallback decisions) before its executor can write `services/compare.py`. The original spike design pointed at `get_index_path()` (user cache) for data — that is mutable, may be missing, and may force a slow rebuild. RESEARCH §Q3(a)/§Q4(a) already documents the exact post-markdownify prose forms; this spike re-verifies them against a reproducible fixture (mirroring `tests/test_multi_version.py::multi_version_db`) so the evidence file is bit-for-bit re-runnable in CI, on a fresh checkout, and offline.
+
+Output: `09-01-data-shape-spike-SUMMARY.md` recording (a) the in-memory fixture used, (b) the post-extraction regex matches per probe, (c) the locked regex literals or fallback decisions, and (d) an optional `## Optional live-index cross-check` if the executor chose to additionally spot-check a real `index.db`.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@AGENTS.md
+@.planning/ROADMAP.md
+@.planning/phases/09-compare-versions/09-CONTEXT.md
+@.planning/phases/09-compare-versions/09-RESEARCH.md
+@tests/test_multi_version.py
+@tests/conftest.py
+
+<interfaces>
+<!-- The fixture pattern to clone (in-memory, reproducible, no user-cache dependency). -->
+
+From src/mcp_server_python_docs/storage/db.py:
+```python
+def get_readwrite_connection(db_path: Path) -> sqlite3.Connection: ...
+def bootstrap_schema(conn: sqlite3.Connection) -> None: ...
+```
+
+Relevant schema (from src/mcp_server_python_docs/storage/schema.sql):
+```sql
+CREATE TABLE doc_sets (id, source, version, language, label, is_default, base_url, ...);
+CREATE TABLE documents (id, doc_set_id, uri, slug, title, content_text, char_count, ...);
+CREATE TABLE sections (id, document_id, uri, anchor, heading, level, ordinal, content_text, char_count, ...);
+CREATE TABLE symbols (id, doc_set_id, qualified_name, normalized_name, module, symbol_type, document_id, section_id, uri, anchor, ...);
+```
+
+Fixture pattern from tests/test_multi_version.py lines 17-81:
+```python
+@pytest.fixture
+def multi_version_db(tmp_path):
+    db_path = tmp_path / "test.db"
+    conn = get_readwrite_connection(db_path)
+    bootstrap_schema(conn)
+    # INSERT two doc_sets + documents + sections + symbols
+    # INSERT INTO sections_fts(sections_fts) VALUES('rebuild')
+    yield conn
+    conn.close()
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Build the in-memory spike fixture with known Sphinx-directive prose</name>
+  <read_first>
+    - tests/test_multi_version.py lines 17-81 (the multi_version_db fixture pattern — already in context)
+    - src/mcp_server_python_docs/storage/db.py (bootstrap_schema + get_readwrite_connection signatures)
+    - src/mcp_server_python_docs/storage/schema.sql (full schema — doc_sets / documents / sections / symbols columns)
+    - .planning/phases/09-compare-versions/09-RESEARCH.md Q3(a) lines 170-184 (canonical post-markdownify prose forms for `.. versionadded::` / `.. changed::` / `.. deprecated::`) and Q4(a) lines 197-210 (`.. seealso::` prose form)
+  </read_first>
+  <action>
+    Write a standalone Python script `tests/test_compare_versions_spike.py` (or a notebook-style inline `uv run python -c "..."` if the executor prefers; the script form is preferred because it is rerunnable in CI). The script builds a temporary SQLite DB matching the multi_version_db shape, with two doc_sets (`3.10` not-default, `3.11` default) and four section rows carrying the EXACT post-markdownify prose forms that RESEARCH §Q3/§Q4 documents:
+
+    (a) `(doc_set=3.11, slug='library/asyncio-task.html', anchor='asyncio.TaskGroup')` — `content_text = "An asynchronous context manager holding a group of tasks.\n\nNew in version 3.11."`
+    (b) `(doc_set=3.11, slug='library/asyncio-runner.html', anchor='asyncio.run')` — `content_text = "Execute the coroutine and return the result.\n\nChanged in version 3.10: Added support for ..."`
+    (c) `(doc_set=3.11, slug='library/somemodule.html', anchor='some.deprecated_func')` — `content_text = "Old API.\n\nDeprecated since version 3.12: use new_func() instead."`
+    (d) `(doc_set=3.11, slug='library/pathlib.html', anchor='pathlib.Path')` — `content_text = "Concrete path classes.\n\nSee also\n\n[os.path](library/os.path.html) — Operating system path manipulation.\n[fnmatch](library/fnmatch.html) — Pattern matching."`
+
+    These prose forms are NOT invented — they are the literal forms RESEARCH §Q3(a) lines 170-184 documents as surviving the markdownify call in `sphinx_json.py:247`. The spike's job is to lock the regex strings against this controlled fixture, not to rediscover what RESEARCH already proved.
+
+    The script must build the fixture in-memory or under `tempfile.TemporaryDirectory()` — it must NOT touch `get_index_path()` and must NOT trigger a `build-index` rebuild. The script must be re-runnable on a fresh clone with `uv run python tests/test_compare_versions_spike.py` exiting 0.
+  </action>
+  <verify>
+    <automated>uv run python -c "import tempfile, pathlib, sqlite3; from mcp_server_python_docs.storage.db import bootstrap_schema, get_readwrite_connection; td=tempfile.mkdtemp(); p=pathlib.Path(td)/'spike.db'; c=get_readwrite_connection(p); bootstrap_schema(c); c.execute(\"INSERT INTO doc_sets (source, version, language, label, is_default, base_url) VALUES ('python-docs', '3.11', 'en', 'Python 3.11', 1, 'x')\"); ds=c.execute('SELECT id FROM doc_sets').fetchone()[0]; c.execute(\"INSERT INTO documents (doc_set_id, uri, slug, title, content_text, char_count) VALUES (?, 'library/asyncio-task.html', 'library/asyncio-task.html', 't', '', 0)\", (ds,)); d=c.execute('SELECT id FROM documents').fetchone()[0]; c.execute(\"INSERT INTO sections (document_id, uri, anchor, heading, level, ordinal, content_text, char_count) VALUES (?, 'library/asyncio-task.html#asyncio.TaskGroup', 'asyncio.TaskGroup', 'TaskGroup', 2, 0, 'New in version 3.11.', 20)\", (d,)); c.commit(); print('spike fixture OK')"</automated>
+  </verify>
+  <acceptance_criteria>
+    - Source: a standalone re-runnable Python entry point exists (either `tests/test_compare_versions_spike.py` or the SUMMARY embeds the script) that builds the fixture under `tempfile.TemporaryDirectory()` — no user-cache dependency.
+    - Source: the script does NOT import `get_index_path`, does NOT call `build-index`, and does NOT touch `~/Library/Caches/mcp-python-docs/` or `~/.cache/mcp-python-docs/`. Verify by grep: the script does NOT contain the string `get_index_path` or `build-index` or `Caches/mcp-python-docs` or `.cache/mcp-python-docs`.
+    - CLI: the verify command exits 0 and prints `spike fixture OK`, confirming `bootstrap_schema` + INSERTs work with the prose forms RESEARCH documents.
+  </acceptance_criteria>
+  <done>A reproducible, offline, no-side-effects fixture builder exists; running it produces the four seeded section rows.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Probe each Sphinx-directive prose form with its candidate regex</name>
+  <read_first>
+    - .planning/phases/09-compare-versions/09-RESEARCH.md Q3(a)-(c) (regex candidates: `_NEW_IN_RE`, `_CHANGED_IN_RE`, `_DEPRECATED_IN_RE`)
+    - .planning/phases/09-compare-versions/09-RESEARCH.md Q4(c) (`_SEE_ALSO_LINK_RE`)
+    - The fixture from Task 1 (already in context)
+  </read_first>
+  <action>
+    Against the fixture from Task 1, run each candidate regex from RESEARCH and record the match:
+
+    | Probe | content_text excerpt | Candidate regex | Expected capture |
+    |-------|----------------------|-----------------|------------------|
+    | A1 (versionadded) | `"New in version 3.11."` | `r"New in version\s+(\d+\.\d+)"` | `"3.11"` |
+    | Sibling 1 (changed) | `"Changed in version 3.10: ..."` | `r"Changed in version\s+(\d+\.\d+)"` | `"3.10"` |
+    | Sibling 2 (deprecated) | `"Deprecated since version 3.12: ..."` | `r"Deprecated since version\s+(\d+\.\d+)"` | `"3.12"` |
+    | A2 (seealso) | `"See also\n\n[os.path](...)\n[fnmatch](...)"` | `r"\[([^\]]+)\]\("` (anchored to "See also" window) | `["os.path", "fnmatch"]` |
+
+    For each row: if the candidate regex captures the expected value → record `HOLDS` and lock the literal. If the candidate fails → record `FALSIFIED` and lock the fallback (`None` for scalar extractors, `[]` for `_extract_see_also`). Record the outcome per probe in the SUMMARY's `## A1 result` / `## A2 result` / `## Sibling directive results` sections.
+
+    Note: against this controlled fixture, all four are expected to HOLD because the fixture seeds the exact prose form RESEARCH documents. The probe is therefore a tautological verification — its real value is producing a self-contained, re-runnable evidence file. The executor MUST still run the probes (do not just copy the expected outcomes) so that the SUMMARY contains real `re.search` outputs.
+  </action>
+  <verify>
+    <automated>uv run python -c "import re; assert re.search(r'New in version\s+(\d+\.\d+)', 'New in version 3.11.').group(1) == '3.11'; assert re.search(r'Changed in version\s+(\d+\.\d+)', 'Changed in version 3.10: x').group(1) == '3.10'; assert re.search(r'Deprecated since version\s+(\d+\.\d+)', 'Deprecated since version 3.12: y').group(1) == '3.12'; assert re.findall(r'\[([^\]]+)\]\(', 'See also\n\n[os.path](x)\n[fnmatch](y)') == ['os.path', 'fnmatch']; print('all 4 probes HOLD')"</automated>
+  </verify>
+  <acceptance_criteria>
+    - CLI: the verify command exits 0 and prints `all 4 probes HOLD`.
+    - Source: SUMMARY records each probe's outcome with the actual captured value (or `None`/`[]` if FALSIFIED).
+    - Source: the regex strings recorded in SUMMARY match the literals tested by the verify command — no drift between probe and lock.
+  </acceptance_criteria>
+  <done>All four regex extractors have a HOLDS/FALSIFIED outcome backed by a real `re.search` call against the fixture's seeded prose.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Write 09-01 SUMMARY with locked extractor decisions</name>
+  <read_first>
+    - $HOME/.claude/get-shit-done/templates/summary.md
+    - The probe outputs collected in Tasks 1-2 (already in context)
+  </read_first>
+  <action>
+    Create `.planning/phases/09-compare-versions/09-01-data-shape-spike-SUMMARY.md`. Sections required, in order:
+
+    `## Spike data source` — Document that the spike used an in-memory fixture (NOT the user cache). Include the path-pattern (`tempfile.mkdtemp()` or `tests/test_compare_versions_spike.py`) and a one-line invocation command that reproduces the spike on a fresh checkout.
+
+    `## Seeded prose forms` — Per-row table mapping `(version, slug, anchor)` to the verbatim `content_text` used for each probe, cross-referenced to RESEARCH §Q3/§Q4.
+
+    `## A1 result` (HOLDS / FALSIFIED + captured value)
+    `## A2 result` (HOLDS / FALSIFIED + captured link labels)
+    `## Sibling directive results` (Changed-in / Deprecated-since — HOLDS / FALSIFIED + captured values)
+
+    `## Locked regex patterns` (exact Python raw-string regex literals, ready to paste into `services/compare.py`):
+      - `_NEW_IN_RE = r"New in version\s+(\d+\.\d+)"` (or `None` if A1 falsified)
+      - `_CHANGED_IN_RE = r"Changed in version\s+(\d+\.\d+)"`
+      - `_DEPRECATED_IN_RE = r"Deprecated since version\s+(\d+\.\d+)"`
+      - `_SEE_ALSO_LINK_RE = r"\[([^\]]+)\]\("`
+
+    `## Fallback policy` — Per extractor, what to return when no match: `None` for scalar extractors (`_extract_new_in`, `_extract_changed_in`, `_extract_deprecated_in`); `[]` for `_extract_see_also`.
+
+    `## Optional live-index cross-check` — OPTIONAL section. If the executor additionally spot-checked a real `index.db` and the prose forms there match, record it here as supplementary evidence. If the executor skipped this (which is fine), record `Not performed — fixture is the authoritative source per the revised spike scope.`
+
+    `## Implications for Plan 03` — 1-3 sentences directing Plan 03's executor: "All four extractors HOLD against the seeded fixture — implement as documented in RESEARCH §Q3/Q4. If live `index.db` shows different prose forms during Plan 03 implementation, raise a finding rather than mutating the regex unilaterally."
+  </action>
+  <verify>
+    <automated>test -f .planning/phases/09-compare-versions/09-01-data-shape-spike-SUMMARY.md && grep -q "## Spike data source" .planning/phases/09-compare-versions/09-01-data-shape-spike-SUMMARY.md && grep -q "## Locked regex patterns" .planning/phases/09-compare-versions/09-01-data-shape-spike-SUMMARY.md && grep -q "## A1 result" .planning/phases/09-compare-versions/09-01-data-shape-spike-SUMMARY.md && grep -q "## A2 result" .planning/phases/09-compare-versions/09-01-data-shape-spike-SUMMARY.md && grep -q "## Fallback policy" .planning/phases/09-compare-versions/09-01-data-shape-spike-SUMMARY.md && grep -q "## Implications for Plan 03" .planning/phases/09-compare-versions/09-01-data-shape-spike-SUMMARY.md && ! grep -q "get_index_path" .planning/phases/09-compare-versions/09-01-data-shape-spike-SUMMARY.md</automated>
+  </verify>
+  <acceptance_criteria>
+    - Source: file `.planning/phases/09-compare-versions/09-01-data-shape-spike-SUMMARY.md` exists with the seven required section headings exactly.
+    - Source: file does NOT contain `get_index_path` (verified by the negative grep above) — confirming the spike did not depend on the user cache.
+    - Behavior: Plan 03's executor can copy the regex literals from `## Locked regex patterns` verbatim into `services/compare.py` without re-probing anything.
+  </acceptance_criteria>
+  <done>The SUMMARY is checked into the worktree (uncommitted is fine — Plan 03 picks it up immediately).</done>
+</task>
+
+</tasks>
+
+<verification>
+- The spike is reproducible on a fresh clone, offline, with no `index.db` dependency.
+- All four extractor decisions (`new_in`, `changed_in`, `deprecated_in`, `see_also`) are recorded as locked-regex-or-fallback in the SUMMARY.
+- The SUMMARY explicitly documents that the user cache was NOT used as the data source.
+- No source code under `src/` is modified by this plan (it is a pure spike).
+</verification>
+
+<success_criteria>
+- `09-01-data-shape-spike-SUMMARY.md` exists at the path declared in `files_modified`.
+- The seven required section headings are present (verified by the Task 3 grep gate).
+- The Implications-for-Plan-03 line tells the next executor exactly what to lock in.
+- The spike artifact is bit-reproducible offline — running the spike script on a clean checkout produces identical probe outputs.
+</success_criteria>
+
+<output>
+Create `.planning/phases/09-compare-versions/09-01-data-shape-spike-SUMMARY.md` when done.
+</output>