[v0.3.0] docs — write ADR-001 (Source Adapters)

[ayhammouda]

Closes #50

Acceptance criteria

• docs/architecture/ADR-001-source-adapters.md exists and fills every section of the template embedded below. — Added the ADR with all required template sections and checked section headings locally.
• Status Accepted, date 2026-05-29, decider @ayhammouda. — ADR front matter contains those exact values.
• The ADR documents the two source adapters that exist today: (1) CPython documentation source — cloned at a pinned ref, built via sphinx-build -b json (point at ingestion/); (2) PyPI metadata source — lookup_package_docs controlled metadata fetch (point at services/package_docs.py). — ADR cites cpython_versions.py, __main__.py, sphinx_json.py, inventory.py, and services/package_docs.py.
• It states principle 2.1 (canonical source only — no scraped mirrors) and 2.2 (offline-first at query time), and explicitly names the one documented exception: lookup_package_docs performs a controlled PyPI metadata lookup, which is a build/lookup-time network call, not a docs-query-time call. — ADR states the principles and exception in Decision Drivers, Decision Outcome, and Layer Contract.
• The "Layer Contract" section specifies the source-connector layer's inputs (version/identifier), outputs (canonical artifacts handed to ingestion), and invariants (pinned, reproducible, no third-party indexers), per principle 2.7. — ADR includes explicit Inputs, Outputs, and Invariants bullets.
• uv run python-docs-mcp-server doctor passes (docs-only change). — Doctor passed locally with all checks green.

Validation gate output

$ uv run ruff check src/ tests/
All checks passed!

$ uv run pyright src/
0 errors, 0 warnings, 0 informations

$ uv run pytest --tb=short -q
298 passed in 24.13s

$ uv run python-docs-mcp-server doctor
All checks passed.

Additional issue-specific checks:

ADR path exists
ADR content check: pass
ADR link check: pass

CodeRabbit review

Pending.

Why this approach

The issue fully prescribed a docs-only ADR. I verified the claims against the current source files and wrote one new architecture document without changing code, schema, workflows, or public behavior.

Why this triggered supervisor review

None.

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (1)

• docs/architecture/ADR-001-source-adapters.md is excluded by none and included by none

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7406a23e-ee27-419f-a1a9-9ba2567b5cdb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/50-adr-source-adapters

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ayhammouda]

Heimdall verification passed for PR #57 at 22ad69d564de85dfa3e4222e930bb0b96b57849b.

Evidence from a fresh isolated checkout at /tmp/heimdall-pr57-python-docs-mcp-server:

$ git diff --name-status origin/main...HEAD
A	docs/architecture/ADR-001-source-adapters.md

$ git diff --check origin/main...HEAD
# pass

$ uv sync --dev
# pass

$ uv run ruff check src/ tests/
All checks passed!

$ uv run pyright src/
0 errors, 0 warnings, 0 informations

$ uv run pytest --tb=short -q
298 passed in 23.97s

$ uv run python-docs-mcp-server doctor
All checks passed.

Docs-only ADR checks:

ADR exists: docs/architecture/ADR-001-source-adapters.md
Template sections present: Context and Problem Statement, Decision Drivers, Considered Options, Decision Outcome, Consequences, Layer Contract, Links
Required metadata present: Status Accepted, Date 2026-05-29, Deciders @ayhammouda
Local markdown links checked: 10, all resolve

Scope/claim verification:

• Diff is docs-only and adds exactly one file under docs/architecture/.
• No source, tests, schema, workflows, release config, README hero, or governing policy files changed.
• ADR claims were checked against src/mcp_server_python_docs/__main__.py, ingestion/cpython_versions.py, ingestion/sphinx_json.py, ingestion/inventory.py, services/package_docs.py, and STRATEGIC-ROADMAP-2026-05-29.md principles 2.1, 2.2, and 2.7.
• The ADR documents the two current source adapters: pinned CPython docs build path and controlled PyPI metadata lookup for lookup_package_docs.

CodeRabbit triage: gh pr checks reports CodeRabbit pass / Review completed; PR comment says review was skipped due path filters for the single docs file, and GraphQL review threads returned zero nodes. No unresolved CodeRabbit findings.

Label action: replacing verification-needed with verified. No merge or approval performed.