[v0.3.0] ingestion — pin CPython source by commit SHA

[ayhammouda]

Closes #51

Acceptance criteria

• CPythonDocsBuildConfig gains a sha: str field; each of the five entries in CPYTHON_DOCS_BUILD_CONFIG carries the 40-char lowercase-hex commit SHA that the existing tag currently resolves to. The tag field is kept for human readability with a comment noting the SHA is authoritative. — Implemented in src/mcp_server_python_docs/ingestion/cpython_versions.py; resolved with git ls-remote https://github.com/python/cpython.git 'refs/tags/v3.10.20^{}' 'refs/tags/v3.11.15^{}' 'refs/tags/v3.12.13^{}' 'refs/tags/v3.13.13^{}' 'refs/tags/v3.14.4^{}'.
• After the clone in __main__.py, the code verifies git -C <clone_dir> rev-parse HEAD equals config["sha"] and aborts on mismatch with a clear error. — Added _verify_cpython_source_sha; mismatch logs version/tag/actual/expected SHA and raises SystemExit(1) before Sphinx setup or content ingestion.
• tests/test_ingestion.py asserts every config entry has a sha matching ^[0-9a-f]{40}$, alongside the existing tag assertion. — Added regex assertion in the existing config loop.
• uv run pytest tests/test_ingestion.py -q passes. — 42 passed in 1.10s.
• A draft SECURITY.md threat-model paragraph is written into the PR description and the context file's decision log; SECURITY.md itself is not edited. — Added below and in .planning/agent-context/cpython-source-sha-pin.md; SECURITY.md untouched.

SHA verification evidence

$ git ls-remote https://github.com/python/cpython.git 'refs/tags/v3.10.20^{}' 'refs/tags/v3.11.15^{}' 'refs/tags/v3.12.13^{}' 'refs/tags/v3.13.13^{}' 'refs/tags/v3.14.4^{}'
842e987df856a5d4db37933c62a3456930a19092	refs/tags/v3.10.20^{}
2340a037f7450e70fccfe411e6531afb4d57a312	refs/tags/v3.11.15^{}
3bb231a6a5dc02b95658877318bf61501a7209e9	refs/tags/v3.12.13^{}
01104ce1beb3135c2e0c01ec835b994c1f55a1c0	refs/tags/v3.13.13^{}
23116f998f6789d8c2fbe5ed5b8146854c8c2a4f	refs/tags/v3.14.4^{}

Draft SECURITY.md threat-model paragraph

The largest build-time supply-chain input is the build-index clone of the upstream CPython repository, which provides the source tree used to generate canonical documentation content. Each supported CPython docs release is pinned to the exact commit SHA that its human-readable release tag currently resolves to; the tag is retained for operator readability, but the SHA is the authoritative integrity anchor. If a tag is reissued, moved, or otherwise resolves to different source content, the build fails before Sphinx setup or content ingestion rather than silently publishing changed documentation.

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
299 passed in 29.09s

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

$ uv run pytest tests/test_ingestion.py -q
42 passed in 1.10s

$ uv run python-docs-mcp-server validate-corpus
Corpus validation PASSED

$ git diff --check
# no output

CodeRabbit review

Unavailable: CodeRabbit posted rate-limit comments from both configured identities instead of an actionable review. Blocking: None reported. Follow-up: retry @coderabbitai review when quota resets if Vision wants that signal. False positive: None.

Why this approach

The issue prescribed a tag-based shallow clone followed by post-clone SHA verification. Keeping the tag fetch preserves the existing clone behavior while making the pinned commit SHA the authoritative integrity check.

Why this triggered supervisor review

None under AGENT-EXECUTION-PIPELINE.md §7. This PR intentionally includes the SECURITY.md draft text for Vision/human follow-up without editing SECURITY.md.

[coderabbitai]

Warning

Review limit reached

@ayhammouda, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 55 minutes and 43 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 636c5244-c4e4-4dbd-9bc9-ee5e9ab8bfb4

📥 Commits

Reviewing files that changed from the base of the PR and between 5fd9cb2 and 8ed5a36.

⛔ Files ignored due to path filters (1)

• .planning/agent-context/cpython-source-sha-pin.md is excluded by none and included by none

📒 Files selected for processing (3)

• src/mcp_server_python_docs/__main__.py
• src/mcp_server_python_docs/ingestion/cpython_versions.py
• tests/test_ingestion.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/51-cpython-source-sha-pin

---

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.}

[coderabbiteu]

Warning

Review limit reached

@ayhammouda, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 55 minutes and 42 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 141059e6-b88c-4bdc-91e3-d5592b6a7a4a

📥 Commits

Reviewing files that changed from the base of the PR and between 5fd9cb2 and 8ed5a36.

⛔ Files ignored due to path filters (1)

• .planning/agent-context/cpython-source-sha-pin.md is excluded by none and included by none

📒 Files selected for processing (3)

• src/mcp_server_python_docs/__main__.py
• src/mcp_server_python_docs/ingestion/cpython_versions.py
• tests/test_ingestion.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/51-cpython-source-sha-pin

---

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 head 8ed5a365ae2f16ae7cb628ef8a5e4932d4ca2d2f.

Scope checked against issue #51 and forge protocol:

• Changed files are limited to .planning/agent-context/cpython-source-sha-pin.md, src/mcp_server_python_docs/__main__.py, src/mcp_server_python_docs/ingestion/cpython_versions.py, and tests/test_ingestion.py.
• SECURITY.md was not edited. Draft threat-model wording is present in the PR body and .planning/agent-context/cpython-source-sha-pin.md only.
• CPython tags remain for readability; authoritative 40-hex SHAs are now in CPYTHON_DOCS_BUILD_CONFIG.
• _verify_cpython_source_sha() runs immediately after the shallow tag clone and before Sphinx setup/content ingestion.

Commands run from fresh isolated checkout /tmp/heimdall-pr59-python-docs:

uv sync --dev
uv run ruff check src/ tests/                         # pass
uv run pyright src/                                   # 0 errors, 0 warnings, 0 informations
uv run pytest --tb=short -q                           # 299 passed in 24.77s
uv run python-docs-mcp-server doctor                  # All checks passed
uv run pytest tests/test_ingestion.py -q              # 42 passed in 0.99s
uv run python-docs-mcp-server validate-corpus         # Corpus validation PASSED
git ls-remote https://github.com/python/cpython.git 'refs/tags/v3.10.20^{}' 'refs/tags/v3.11.15^{}' 'refs/tags/v3.12.13^{}' 'refs/tags/v3.13.13^{}' 'refs/tags/v3.14.4^{}'
uv run python - <<'PY' ... SHA regex/config assertion ... PY
uv run python - <<'PY' ... mismatch helper assertion ... PY

SHA evidence independently matched config:

842e987df856a5d4db37933c62a3456930a19092  refs/tags/v3.10.20^{}
2340a037f7450e70fccfe411e6531afb4d57a312  refs/tags/v3.11.15^{}
3bb231a6a5dc02b95658877318bf61501a7209e9  refs/tags/v3.12.13^{}
01104ce1beb3135c2e0c01ec835b994c1f55a1c0  refs/tags/v3.13.13^{}
23116f998f6789d8c2fbe5ed5b8146854c8c2a4f  refs/tags/v3.14.4^{}

Mismatch abort behavior verified with a monkeypatched git rev-parse HEAD: the helper logged the actual/expected SHA mismatch and raised SystemExit(1).

GitHub/CodeRabbit status:

• gh pr checks 59 shows CI matrix, Security Audit dependency audit, CodeQL Analyze/CodeQL, and CodeRabbit all passing.
• CodeRabbit review threads via GraphQL: none.
• CodeRabbit comments are rate-limit/usage-credit notices only, no actionable findings.

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